@rabbit-company/logger 5.1.0 → 5.3.0

package/README.md

@@ -4,20 +4,17 @@
 [![JSR Version](https://jsr.io/badges/@rabbit-company/logger)](https://jsr.io/@rabbit-company/logger)
 [![License](https://img.shields.io/npm/l/@rabbit-company/logger)](LICENSE)
 
-A versatile, multi-transport logging library for Node.js and browser environments with support for:
-
-- Console output (with colors and custom formatting)
-- NDJSON (Newline Delimited JSON)
-- Grafana Loki (with batching and label management)
+A high-performance, multi-transport logging library for Node.js and browser environments with first-class TypeScript support.
 
 ## Features ✨
 
-- **Multiple log levels**: ERROR, WARN, AUDIT, INFO, HTTP, DEBUG, VERBOSE, SILLY
-- **Structured logging**: Attach metadata objects to log entries
-- **Transport system**: Console, NDJSON, and Loki transports included
-- **Loki optimized**: Automatic label management and batching
-- **TypeScript ready**: Full type definitions included
-- **Cross-platform**: Works in Node.js, Deno, Bun and browsers
+- **Multi-level logging**: 8 severity levels from ERROR to SILLY
+- **Structured logging**: Attach rich metadata to log entries
+- **Multiple transports**: Console, NDJSON, Grafana Loki and Syslog
+- **Advanced formatting**: Customizable console output with extensive datetime options
+- **Production-ready**: Batching, retries, and queue management for Loki
+- **Cross-platform**: Works in Node.js, Deno and Bun
+- **Type-safe**: Full TypeScript definitions included
 
 ## Installation 📦
 
@@ -38,16 +35,40 @@ pnpm add @rabbit-company/logger
 import { Logger, Levels } from "@rabbit-company/logger";
 
 // Create logger with default console transport
-const logger = new Logger({ level: Levels.DEBUG });
+const logger = new Logger({
+	level: Levels.DEBUG, // Show DEBUG and above
+});
 
-// Log messages with metadata
-logger.info("Application started", { version: "1.0.0" });
+// Simple log
+logger.info("Application starting...");
+
+// Structured logging
 logger.error("Database connection failed", {
 	error: "Connection timeout",
 	attempt: 3,
+	db: "primary",
+});
+
+// Audit logging
+logger.audit("User login", {
+	userId: "usr_123",
+	ip: "192.168.1.100",
 });
 ```
 
+## Log Levels 📊
+
+| Level   | Description                     | Typical Use Case                      |
+| ------- | ------------------------------- | ------------------------------------- |
+| ERROR   | Critical errors                 | System failures, unhandled exceptions |
+| WARN    | Potential issues                | Deprecations, rate limiting           |
+| AUDIT   | Security events                 | Logins, permission changes            |
+| INFO    | Important runtime information   | Service starts, config changes        |
+| HTTP    | HTTP traffic                    | Request/response logging              |
+| DEBUG   | Debug information               | Flow tracing, variable dumps          |
+| VERBOSE | Very detailed information       | Data transformations                  |
+| SILLY   | Extremely low-level information | Inner loop logging                    |
+
 ## Console Formatting 🖥️
 
 The console transport supports extensive datetime formatting:
@@ -115,135 +136,66 @@ const logger = new Logger({
 console.log(ndjsonTransport.getData());
 ```
 
-### Loki Transport
+### Loki Transport (Grafana)
 
 ```js
 import { LokiTransport } from "@rabbit-company/logger";
 
+const lokiTransport = new LokiTransport({
+	url: "http://localhost:3100",
+	labels: {
+		app: "test",
+		env: process.env.NODE_ENV,
+	},
+	basicAuth: {
+		username: process.env.LOKI_USER,
+		password: process.env.LOKI_PASS,
+	},
+	batchSize: 50, // Send batches of 50 logs
+	batchTimeout: 5000, // Max 5s wait per batch
+	maxQueueSize: 10000, // Keep max 10,000 logs in memory
+	debug: true, // Log transport errors
+});
+
 const logger = new Logger({
-	transports: [
-		new LokiTransport({
-			url: "http://localhost:3100",
-			labels: { app: "my-app", env: "production" },
-			basicAuth: { username: "user", password: "pass" },
-			maxLabelCount: 30,
-		}),
-	],
+	transports: [lokiTransport],
 });
 ```
 
-## API Reference 📚
-
-### Log Levels
+### Syslog Transport
 
 ```js
-enum Levels {
-  ERROR,    // Critical errors
-  WARN,     // Warnings
-  AUDIT,    // Security audits
-  INFO,     // Informational
-  HTTP,     // HTTP traffic
-  DEBUG,    // Debugging
-  VERBOSE,  // Detailed tracing
-  SILLY     // Very low-level
-}
-```
+import { SyslogTransport } from "@rabbit-company/logger";
+
+const syslogTransport = new SyslogTransport({
+	host: "syslog.example.com",
+	port: 514,
+	protocol: "udp", // 'udp', 'tcp', or 'tcp-tls'
+	facility: 16, // local0 facility
+	appName: "my-app",
+	protocolVersion: 5424, // 3164 (BSD) or 5424 (modern)
+	tlsOptions: {
+		ca: fs.readFileSync("ca.pem"),
+		rejectUnauthorized: true,
+	},
+	maxQueueSize: 2000, // Max queued messages during outages
+	debug: true, // Log connection status
+});
 
-### Logging Methods
+const logger = new Logger({
+	transports: [syslogTransport],
+});
 
-```js
-logger.error(message: string, metadata?: object): void
-logger.warn(message: string, metadata?: object): void
-logger.audit(message: string, metadata?: object): void
-logger.info(message: string, metadata?: object): void
-logger.http(message: string, metadata?: object): void
-logger.verbose(message: string, metadata?: object): void
-logger.debug(message: string, metadata?: object): void
-logger.silly(message: string, metadata?: object): void
+// Features:
+// - Automatic reconnection with exponential backoff
+// - Message queuing during network issues
+// - Supports UDP, TCP, and TLS encryption
+// - Compliant with RFC 3164 and RFC 5424
 ```
 
-### Types
-
-```ts
-/**
- * Represents a single log entry with message, severity level, timestamp, and optional metadata
- */
-export interface LogEntry {
-	/** The log message content */
-	message: string;
-	/** Severity level of the log entry */
-	level: Levels;
-	/** Timestamp in milliseconds since epoch */
-	timestamp: number;
-	/** Optional structured metadata associated with the log */
-	metadata?: Record<string, any>;
-}
-
-/**
- * Interface for log transport implementations
- */
-export interface Transport {
-	/**
-	 * Processes and outputs a log entry
-	 * @param entry The log entry to process
-	 */
-	log: (entry: LogEntry) => void;
-}
-
-/**
- * Configuration options for the Logger instance
- */
-export interface LoggerConfig {
-	/** Minimum log level to output (default: INFO) */
-	level?: Levels;
-	/** Enable colored output (default: true) */
-	colors?: boolean;
-	/** Format string using {date}, {type}, {message} placeholders (default: "[{date}] {type} {message}") */
-	format?: string;
-	/** Array of transports to use (default: [ConsoleTransport]) */
-	transports?: Transport[];
-}
-
-/**
- * Configuration for Loki transport
- */
-export interface LokiConfig {
-	/** Loki server URL (e.g., "http://localhost:3100") */
-	url: string;
-	/** Base labels to attach to all logs */
-	labels?: Record<string, string>;
-	/** Basic authentication credentials */
-	basicAuth?: {
-		username: string;
-		password: string;
-	};
-	/** Number of logs to batch before sending (default: 10) */
-	batchSize?: number;
-	/** Maximum time in ms to wait before sending a batch (default: 5000) */
-	batchTimeout?: number;
-	/** Tenant ID for multi-tenant Loki setups */
-	tenantID?: string;
-	/** Maximum number of labels allowed (default: 50) */
-	maxLabelCount?: number;
-	/** Enable debug logging for transport errors (default: false) */
-	debug?: boolean;
-}
-
-/**
- * Represents a Loki log stream with labels and log values
- */
-export interface LokiStream {
-	/** Key-value pairs of log labels */
-	stream: {
-		/** Log level label (required) */
-		level: string;
-		/** Additional custom labels */
-		[key: string]: string;
-	};
-	/** Array of log entries with [timestamp, message] pairs */
-	values: [[string, string]];
-}
-```
+## API Reference 📚
+
+Full API documentation is available in the [TypeScript definitions](https://github.com/Rabbit-Company/Logger-JS/blob/main/src/types.ts).
 
 ## Advanced Usage 🛠️
 

package/module/logger.d.ts

@@ -110,6 +110,23 @@ export declare enum Levels {
 }
 /**
  * Represents a single log entry with message, severity level, timestamp, and optional metadata
+ *
+ * @interface LogEntry
+ * @property {string} message - The primary log message content
+ * @property {Levels} level - Severity level of the log entry
+ * @property {number} timestamp - Unix timestamp in milliseconds since epoch
+ * @property {Object.<string, any>} [metadata] - Optional structured metadata associated with the log
+ *
+ * @example
+ * {
+ *   message: "User login successful",
+ *   level: Levels.INFO,
+ *   timestamp: Date.now(),
+ *   metadata: {
+ *     userId: "12345",
+ *     ipAddress: "192.168.1.100"
+ *   }
+ * }
  */
 export interface LogEntry {
 	/** The log message content */
@@ -122,50 +139,168 @@ export interface LogEntry {
 	metadata?: Record<string, any>;
 }
 /**
- * Interface for log transport implementations
+ * Interface that all log transport implementations must adhere to
+ *
+ * @interface Transport
+ *
+ * @example
+ * class CustomTransport implements Transport {
+ *   log(entry: LogEntry) {
+ *     // Custom log handling implementation
+ *   }
+ * }
  */
 export interface Transport {
 	/**
 	 * Processes and outputs a log entry
-	 * @param entry The log entry to process
+	 * @param {LogEntry} entry - The log entry to process
+	 * @returns {void}
 	 */
 	log: (entry: LogEntry) => void;
 }
 /**
  * Configuration options for the Logger instance
+ *
+ * @interface LoggerConfig
+ * @property {Levels} [level=Levels.INFO] - Minimum log level to output
+ * @property {boolean} [colors=true] - Enable colored output in console
+ * @property {string} [format="[{datetime-local}] {type} {message}"] - Format string supporting these placeholders:
+ *
+ * ## Time/Date Placeholders
+ *
+ * ### UTC Formats
+ * - `{iso}`: Full ISO-8601 format with milliseconds (YYYY-MM-DDTHH:MM:SS.mmmZ)
+ * - `{datetime}`: Simplified ISO without milliseconds (YYYY-MM-DD HH:MM:SS)
+ * - `{date}`: Date component only (YYYY-MM-DD)
+ * - `{time}`: Time component only (HH:MM:SS)
+ * - `{utc}`: Complete UTC string (e.g., "Wed, 15 Nov 2023 14:30:45 GMT")
+ * - `{ms}`: Milliseconds since Unix epoch
+ *
+ * ### Local Time Formats
+ * - `{datetime-local}`: Local date and time (YYYY-MM-DD HH:MM:SS)
+ * - `{date-local}`: Local date only (YYYY-MM-DD)
+ * - `{time-local}`: Local time only (HH:MM:SS)
+ * - `{full-local}`: Complete local string with timezone
+ *
+ * ## Log Content Placeholders
+ * - `{type}`: Log level name (e.g., "INFO", "ERROR")
+ * - `{message}`: The actual log message content
+ *
+ * @property {Transport[]} [transports=[ConsoleTransport]] - Array of transports to use
+ *
+ * @example <caption>Default Format</caption>
+ * {
+ *   format: "[{datetime-local}] {type} {message}"
+ * }
+ *
+ * @example <caption>UTC Time Format</caption>
+ * {
+ *   format: "[{datetime} UTC] {type}: {message}"
+ * }
+ *
+ * @example <caption>Detailed Local Format</caption>
+ * {
+ *   format: "{date-local} {time-local} [{type}] {message}"
+ * }
+ *
+ * @example <caption>Epoch Timestamp</caption>
+ * {
+ *   format: "{ms} - {type} - {message}"
+ * }
  */
 export interface LoggerConfig {
 	/** Minimum log level to output (default: INFO) */
 	level?: Levels;
 	/** Enable colored output (default: true) */
 	colors?: boolean;
-	/** Format string using {date}, {type}, {message} placeholders (default: "[{date}] {type} {message}") */
+	/** Format string using placeholders (default: "[{datetime-local}] {type} {message}") */
 	format?: string;
 	/** Array of transports to use (default: [ConsoleTransport]) */
 	transports?: Transport[];
 }
 /**
- * Configuration for Loki transport
+ * Configuration options for the Loki transport
+ *
+ * @interface LokiConfig
+ *
+ * @example <caption>Basic Configuration</caption>
+ * {
+ *   url: "http://localhost:3100/loki/api/v1/push",
+ *   labels: { app: "frontend", env: "production" }
+ * }
+ *
+ * @example <caption>Advanced Configuration</caption>
+ * {
+ *   url: "http://loki.example.com",
+ *   basicAuth: { username: "user", password: "pass" },
+ *   tenantID: "team-a",
+ *   batchSize: 50,
+ *   batchTimeout: 2000,
+ *   maxQueueSize: 50000,
+ *   maxRetries: 10,
+ *   retryBaseDelay: 2000,
+ *   debug: true
+ * }
  */
 export interface LokiConfig {
-	/** Loki server URL (e.g., "http://localhost:3100") */
+	/**
+	 * Required Loki server endpoint URL
+	 * @example "http://loki.example.com"
+	 */
 	url: string;
-	/** Base labels to attach to all logs */
+	/**
+	 * Base labels attached to all log entries
+	 * @example { app: "frontend", env: "production" }
+	 */
 	labels?: Record<string, string>;
 	/** Basic authentication credentials */
 	basicAuth?: {
+		/** Basic auth username */
 		username: string;
+		/** Basic auth password */
 		password: string;
 	};
-	/** Number of logs to batch before sending (default: 10) */
-	batchSize?: number;
-	/** Maximum time in ms to wait before sending a batch (default: 5000) */
-	batchTimeout?: number;
-	/** Tenant ID for multi-tenant Loki setups */
+	/**
+	 * Tenant ID for multi-tenant Loki installations
+	 * @description Sets the X-Scope-OrgID header
+	 */
 	tenantID?: string;
-	/** Maximum number of labels allowed (default: 50) */
+	/**
+	 * Maximum number of labels allowed per log entry
+	 * @default 50
+	 */
 	maxLabelCount?: number;
-	/** Enable debug logging for transport errors (default: false) */
+	/**
+	 * Number of logs to accumulate before automatic sending
+	 * @default 10
+	 */
+	batchSize?: number;
+	/**
+	 * Maximum time in milliseconds to wait before sending an incomplete batch
+	 * @default 5000
+	 */
+	batchTimeout?: number;
+	/**
+	 * Maximum number of logs to buffer in memory during outages
+	 * @description When reached, oldest logs are dropped
+	 * @default 10000
+	 */
+	maxQueueSize?: number;
+	/**
+	 * Maximum number of attempts to send a failed batch
+	 * @default 5
+	 */
+	maxRetries?: number;
+	/**
+	 * Initial retry delay in milliseconds (exponential backoff base)
+	 * @description Delay doubles with each retry up to maximum 30s
+	 * @default 1000
+	 */
+	retryBaseDelay?: number;
+	/**
+	 * Enable debug logging for transport internals
+	 * @default false
+	 */
 	debug?: boolean;
 }
 /**
@@ -187,6 +322,155 @@ export interface LokiStream {
 		]
 	];
 }
+/**
+ * Configuration options for Syslog transport
+ * @interface SyslogConfig
+ * @description Defines the configuration parameters for establishing a connection
+ * to a syslog server and customizing log message formatting.
+ *
+ * @example
+ * // Basic UDP configuration
+ * const config: SyslogConfig = {
+ *   host: 'logs.example.com',
+ *   port: 514,
+ *   protocol: 'udp'
+ * };
+ *
+ * @example
+ * // Secure TCP with TLS configuration
+ * const secureConfig: SyslogConfig = {
+ *   host: 'secure-logs.example.com',
+ *   port: 6514,
+ *   protocol: 'tcp-tls',
+ *   tlsOptions: {
+ *     ca: fs.readFileSync('ca.pem'),
+ *     cert: fs.readFileSync('client-cert.pem'),
+ *     key: fs.readFileSync('client-key.pem'),
+ *     rejectUnauthorized: true
+ *   },
+ *   appName: 'my-service',
+ *   facility: 16 // local0
+ * };
+ */
+export interface SyslogConfig {
+	/**
+	 * Syslog server hostname or IP address
+	 * @type {string}
+	 * @default 'localhost'
+	 * @example 'logs.example.com'
+	 * @example '192.168.1.100'
+	 */
+	host?: string;
+	/**
+	 * Syslog server port number
+	 * @type {number}
+	 * @default 514
+	 * @example 514 // Standard syslog port
+	 * @example 6514 // Common port for syslog over TLS
+	 */
+	port?: number;
+	/**
+	 * Network protocol to use for syslog transmission
+	 * @type {'udp' | 'tcp' | 'tcp-tls'}
+	 * @default 'udp'
+	 * @description
+	 * - 'udp': Unreliable but fast (RFC 3164 compatible)
+	 * - 'tcp': Reliable connection (RFC 6587)
+	 * - 'tcp-tls': Encrypted connection (RFC 5425)
+	 */
+	protocol?: "udp" | "tcp" | "tcp-tls";
+	/**
+	 * Syslog facility code
+	 * @type {number}
+	 * @range 0-23
+	 * @default 1 // USER
+	 * @description
+	 * Standard syslog facilities:
+	 * - 0: kern     - Kernel messages
+	 * - 1: user     - User-level messages
+	 * - 2: mail     - Mail system
+	 * - 3: daemon   - System daemons
+	 * - 4: auth     - Security/authentication
+	 * - 5: syslog   - Internal syslog messages
+	 * - 6: lpr      - Line printer subsystem
+	 * - 7: news     - Network news subsystem
+	 * - 8: uucp     - UUCP subsystem
+	 * - 9: cron     - Clock daemon
+	 * - 10: authpriv - Security/authentication
+	 * - 11: ftp      - FTP daemon
+	 * - 16-23: local0-local7 - Locally used facilities
+	 */
+	facility?: number;
+	/**
+	 * Application name identifier included in syslog messages
+	 * @type {string}
+	 * @default 'node'
+	 * @description
+	 * Should be a short string (typically <= 32 chars) identifying the application.
+	 * @example 'auth-service'
+	 * @example 'payment-processor'
+	 */
+	appName?: string;
+	/**
+	 * Process ID included in syslog messages
+	 * @type {number}
+	 * @default process.pid
+	 * @description
+	 * Used to identify the specific process generating the log message.
+	 */
+	pid?: number;
+	/**
+	 * Syslog protocol version specification
+	 * @type {3164 | 5424}
+	 * @default 5424
+	 * @description
+	 * - 3164: Traditional BSD syslog format (RFC 3164)
+	 * - 5424: Modern structured syslog format (RFC 5424)
+	 */
+	protocolVersion?: 3164 | 5424;
+	/**
+	 * TLS configuration options for secure connections
+	 * @type {Object}
+	 * @description Required when protocol is 'tcp-tls'
+	 * @property {string} [ca] - PEM encoded CA certificate
+	 * @property {string} [cert] - PEM encoded client certificate
+	 * @property {string} [key] - PEM encoded client private key
+	 * @property {boolean} [rejectUnauthorized=true] - Verify server certificate
+	 */
+	tlsOptions?: {
+		/** CA certificate */
+		ca?: string;
+		/** Client certificate */
+		cert?: string;
+		/** Client private key */
+		key?: string;
+		/** Whether to reject unauthorized certificates (default: true) */
+		rejectUnauthorized?: boolean;
+	};
+	/**
+	 * Maximum number of log messages to buffer in memory
+	 * @type {number}
+	 * @default 1000
+	 * @description
+	 * When the queue reaches this size, oldest messages will be dropped.
+	 * Set to 0 for unlimited (not recommended in production).
+	 */
+	maxQueueSize?: number;
+	/**
+	 * Initial retry delay in milliseconds (exponential backoff base)
+	 * @description Delay doubles with each retry up to maximum 30s
+	 * @default 1000
+	 */
+	retryBaseDelay?: number;
+	/**
+	 * Enable debug output for transport operations
+	 * @type {boolean}
+	 * @default false
+	 * @description
+	 * When true, outputs connection status and error details to console.
+	 */
+	debug?: boolean;
+}
 /**
  * Main Logger class that handles all logging functionality.
  *
@@ -501,84 +785,237 @@ export declare class NDJsonTransport implements Transport {
 	reset(): void;
 }
 /**
- * Transport that sends logs to a Grafana Loki server with batching and retry support.
+ * High-reliability transport for sending logs to Grafana Loki with persistent queuing.
  *
  * Features:
- * - Automatic batching of logs for efficient transmission
- * - Configurable batch size and timeout
+ * - Persistent in-memory queue with configurable size limits
+ * - Exponential backoff retry mechanism with configurable limits
+ * - Automatic batching for efficient network utilization
  * - Label management with cardinality control
  * - Multi-tenancy support via X-Scope-OrgID
- * - Basic authentication support
+ * - Comprehensive error handling and recovery
  *
- * @example
- * // Basic configuration
+ * @implements {Transport}
+ *
+ * @example <caption>Basic Configuration</caption>
  * const lokiTransport = new LokiTransport({
  *   url: "http://localhost:3100",
  *   labels: { app: "my-app", env: "production" }
  * });
  *
- * @example
- * // With authentication and custom batching
- * const securedTransport = new LokiTransport({
+ * @example <caption>Advanced Configuration</caption>
+ * const transport = new LokiTransport({
  *   url: "http://loki.example.com",
+ *   batchSize: 50,
+ *   batchTimeout: 2000,
+ *   maxQueueSize: 50000,
+ *   maxRetries: 10,
+ *   retryBaseDelay: 2000,
+ *   tenantID: "team-a",
  *   basicAuth: { username: "user", password: "pass" },
- *   batchSize: 20,
- *   batchTimeout: 10000 // 10 seconds
+ *   debug: true
  * });
  */
 export declare class LokiTransport implements Transport {
 	private config;
-	private batch;
+	/** @private Internal log queue */
+	private queue;
+	/** @private Current batch size setting */
 	private batchSize;
+	/** @private Current batch timeout setting (ms) */
 	private batchTimeout;
+	/** @private Handle for batch timeout */
 	private timeoutHandle?;
+	/** @private Maximum allowed labels per entry */
 	private maxLabelCount;
+	/** @private Debug mode flag */
 	private debug;
+	/** @private Maximum queue size before dropping logs */
+	private maxQueueSize;
+	/** @private Current retry attempt count */
+	private retryCount;
+	/** @private Maximum allowed retry attempts */
+	private maxRetries;
+	/** @private Base delay for exponential backoff (ms) */
+	private retryBaseDelay;
+	/** @private Handle for retry timeout */
+	private retryTimer?;
+	/** @private Flag indicating active send operation */
+	private isSending;
 	/**
 	 * Creates a new LokiTransport instance
-	 * @param config Configuration options for Loki
-	 * @param config.url Required Loki server URL (e.g., "http://localhost:3100")
-	 * @param config.labels Base labels to attach to all log entries
-	 * @param config.basicAuth Basic authentication credentials
-	 * @param config.batchSize Maximum number of logs to batch before sending (default: 10)
-	 * @param config.batchTimeout Maximum time (ms) to wait before sending a batch (default: 5000)
-	 * @param config.tenantID Tenant ID for multi-tenant Loki setups
-	 * @param config.maxLabelCount Maximum number of labels allowed (default: 50)
-	 * @param config.debug Enable debug logging for transport errors (default: false)
-	 * @throws {Error} If URL is not provided
+	 * @param {LokiConfig} config - Configuration options
+	 * @param {string} config.url - Required Loki server endpoint (e.g., "http://localhost:3100")
+	 * @param {Object.<string, string>} [config.labels] - Base labels attached to all log entries
+	 * @param {Object} [config.basicAuth] - Basic authentication credentials
+	 * @param {string} config.basicAuth.username - Username for basic auth
+	 * @param {string} config.basicAuth.password - Password for basic auth
+	 * @param {string} [config.tenantID] - Tenant ID for multi-tenant Loki installations
+	 * @param {number} [config.batchSize=10] - Number of logs to accumulate before automatic sending
+	 * @param {number} [config.batchTimeout=5000] - Maximum time (ms) to wait before sending incomplete batch
+	 * @param {number} [config.maxLabelCount=50] - Maximum number of labels allowed per log entry
+	 * @param {number} [config.maxQueueSize=10000] - Maximum number of logs to buffer in memory during outages
+	 * @param {number} [config.maxRetries=5] - Maximum number of attempts to send a failed batch
+	 * @param {number} [config.retryBaseDelay=1000] - Initial retry delay in ms (exponential backoff base)
+	 * @param {boolean} [config.debug=false] - Enable debug logging for transport internals
 	 */
 	constructor(config: LokiConfig);
 	/**
-	 * Adds a log entry to the current batch. Automatically sends the batch when:
-	 * - The batch reaches the configured size, OR
-	 * - The batch timeout is reached
+	 * Queues a log entry for delivery to Loki
 	 *
-	 * @param entry The log entry to send. Metadata will be converted to Loki labels
-	 *              following the configured maxLabelCount rules.
+	 * @param {LogEntry} entry - The log entry to process
+	 * @param {string} entry.message - Primary log message content
+	 * @param {string} entry.level - Log severity level (e.g., "INFO", "ERROR")
+	 * @param {number} entry.timestamp - Unix timestamp in milliseconds
+	 * @param {Object} [entry.metadata] - Additional log metadata (will be converted to Loki labels)
 	 *
 	 * @example
 	 * transport.log({
-	 *   message: "User logged in",
-	 *   level: Levels.INFO,
+	 *   message: "User login successful",
+	 *   level: "INFO",
 	 *   timestamp: Date.now(),
-	 *   metadata: { userId: "123", device: "mobile" }
+	 *   metadata: {
+	 *     userId: "12345",
+	 *     sourceIP: "192.168.1.100",
+	 *     device: "mobile"
+	 *   }
 	 * });
 	 */
 	log(entry: LogEntry): void;
 	/**
-	 * Immediately sends the current batch of logs to Loki.
+	 * Schedules the next batch send operation
 	 * @private
+	 * @param {boolean} [immediate=false] - Whether to send immediately without waiting for timeout
+	 */
+	private scheduleSend;
+	/**
+	 * Sends the current batch to Loki with retry logic
+	 * @private
+	 * @async
+	 * @returns {Promise<void>}
 	 *
-	 * Handles:
-	 * - HTTP headers including auth and tenant ID
-	 * - Batch timeout clearing
-	 * - Error logging (when debug enabled)
-	 * - Batch management
-	 *
-	 * Note: This method is called automatically by the transport
-	 * and typically doesn't need to be called directly.
+	 * @description
+	 * Handles the complete send operation including:
+	 * - Preparing HTTP request with proper headers
+	 * - Executing the fetch request
+	 * - Managing retries with exponential backoff
+	 * - Queue cleanup on success/failure
+	 * - Automatic scheduling of next batch
 	 */
 	private sendBatch;
 }
+/**
+ * Syslog transport implementation for the logger library
+ * @class SyslogTransport
+ * @implements {Transport}
+ * @description A robust syslog client that supports UDP, TCP, and TLS-encrypted TCP connections
+ * with automatic reconnection and message queuing capabilities.
+ *
+ * @example
+ * // Basic UDP configuration
+ * const transport = new SyslogTransport({
+ *   host: 'logs.example.com',
+ *   port: 514,
+ *   protocol: 'udp'
+ * });
+ *
+ * @example
+ * // Secure TLS configuration
+ * const secureTransport = new SyslogTransport({
+ *   host: 'secure-logs.example.com',
+ *   port: 6514,
+ *   protocol: 'tcp-tls',
+ *   tlsOptions: {
+ *     ca: fs.readFileSync('ca.pem'),
+ *     rejectUnauthorized: true
+ *   },
+ *   maxQueueSize: 5000
+ * });
+ */
+export declare class SyslogTransport implements Transport {
+	private socket;
+	private queue;
+	private isConnecting;
+	private retryCount;
+	private retryBaseDelay;
+	private maxQueueSize;
+	private debug;
+	private reconnectTimer;
+	private config;
+	/**
+	 * Creates a new SyslogTransport instance
+	 * @constructor
+	 * @param {SyslogConfig} [config={}] - Configuration options for the transport
+	 */
+	constructor(config?: SyslogConfig);
+	/**
+	 * Initializes the appropriate socket based on configured protocol
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeSocket;
+	/**
+	 * Initializes a UDP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeUdpSocket;
+	/**
+	 * Initializes a TCP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeTcpSocket;
+	/**
+	 * Initializes a TLS-secured TCP socket for syslog transmission
+	 * @private
+	 * @returns {void}
+	 */
+	private initializeTlsSocket;
+	/**
+	 * Sets up common event handlers for TCP/TLS sockets
+	 * @private
+	 * @returns {void}
+	 */
+	private setupTcpSocketEvents;
+	/**
+	 * Establishes a TCP connection to the syslog server
+	 * @private
+	 * @returns {void}
+	 */
+	private connectTcpSocket;
+	/**
+	 * Handles socket errors and initiates reconnection if needed
+	 * @private
+	 * @returns {void}
+	 */
+	private handleSocketError;
+	/**
+	 * Sends all queued messages to the syslog server
+	 * @private
+	 * @returns {void}
+	 */
+	private flushQueue;
+	/**
+	 * Sends a single message to the syslog server
+	 * @private
+	 * @param {string} message - The formatted syslog message to send
+	 * @returns {void}
+	 */
+	private sendMessage;
+	/**
+	 * Processes a log entry by formatting and queueing it for transmission
+	 * @public
+	 * @param {LogEntry} entry - The log entry to process
+	 * @returns {void}
+	 */
+	log(entry: LogEntry): void;
+	/**
+	 * Gracefully closes the transport connection
+	 * @public
+	 * @returns {Promise<void>} A promise that resolves when the connection is closed
+	 */
+	close(): Promise<void>;
+}
 
 export {};

package/module/logger.js

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
 // src/constants/colors.ts
 var Colors;
 ((Colors2) => {
@@ -219,40 +222,59 @@ function formatLokiMessage(entry, maxLabelCount, labels = {}) {
 // src/transports/lokiTransport.ts
 class LokiTransport {
   config;
-  batch = [];
+  queue = [];
   batchSize;
   batchTimeout;
   timeoutHandle;
   maxLabelCount;
   debug;
+  maxQueueSize;
+  retryCount = 0;
+  maxRetries;
+  retryBaseDelay;
+  retryTimer;
+  isSending = false;
   constructor(config) {
     this.config = config;
     this.batchSize = config.batchSize || 10;
     this.batchTimeout = config.batchTimeout || 5000;
     this.maxLabelCount = config.maxLabelCount || 50;
     this.debug = config.debug || false;
-    if (!config.url) {
-      throw new Error("Loki URL is required");
-    }
+    this.maxQueueSize = config.maxQueueSize || 1e4;
+    this.maxRetries = config.maxRetries || 5;
+    this.retryBaseDelay = config.retryBaseDelay || 1000;
   }
   log(entry) {
-    const lokiMessage = formatLokiMessage(entry, this.maxLabelCount, { ...this.config.labels, ...entry.metadata });
-    this.batch.push(lokiMessage);
-    if (this.batch.length >= this.batchSize) {
-      this.sendBatch();
-    } else if (!this.timeoutHandle) {
-      this.timeoutHandle = setTimeout(() => this.sendBatch(), this.batchTimeout);
+    const lokiMessage = formatLokiMessage(entry, this.maxLabelCount, {
+      ...this.config.labels,
+      ...entry.metadata
+    });
+    if (this.queue.length >= this.maxQueueSize) {
+      if (this.debug)
+        console.warn("Loki queue full - dropping oldest log entry");
+      this.queue.shift();
     }
+    this.queue.push(lokiMessage);
+    this.scheduleSend();
   }
-  async sendBatch() {
+  scheduleSend(immediate = false) {
+    if (this.isSending)
+      return;
     if (this.timeoutHandle) {
       clearTimeout(this.timeoutHandle);
       this.timeoutHandle = undefined;
     }
-    if (this.batch.length === 0)
+    if (this.queue.length > 0 && (immediate || this.queue.length >= this.batchSize)) {
+      this.sendBatch();
+    } else if (this.queue.length > 0) {
+      this.timeoutHandle = setTimeout(() => this.sendBatch(), this.batchTimeout);
+    }
+  }
+  async sendBatch() {
+    if (this.queue.length === 0 || this.isSending)
       return;
-    const batchToSend = this.batch;
-    this.batch = [];
+    this.isSending = true;
+    const batchToSend = this.queue.slice(0, this.batchSize);
     try {
       const headers = {
         "Content-Type": "application/json"
@@ -270,16 +292,280 @@ class LokiTransport {
           streams: batchToSend.flatMap((entry) => entry.streams)
         })
       });
-      if (!response.ok && this.debug) {
-        console.error("Failed to send logs to Loki: ", await response.text());
+      if (response.ok) {
+        this.queue = this.queue.slice(batchToSend.length);
+        this.retryCount = 0;
+        if (this.retryTimer) {
+          clearTimeout(this.retryTimer);
+          this.retryTimer = undefined;
+        }
+      } else {
+        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
       }
     } catch (error) {
       if (this.debug)
-        console.error("Error sending logs to Loki: ", error);
+        console.error("Loki transmission error: ", error);
+      this.retryCount++;
+      if (this.retryCount <= this.maxRetries) {
+        const delay = Math.min(this.retryBaseDelay * Math.pow(2, this.retryCount - 1), 30000);
+        if (this.debug)
+          console.log(`Scheduling retry #${this.retryCount} in ${delay}ms`);
+        this.retryTimer = setTimeout(() => {
+          this.scheduleSend(true);
+        }, delay);
+      } else {
+        if (this.debug)
+          console.warn(`Max retries (${this.maxRetries}) reached. Dropping batch.`);
+        this.queue = this.queue.slice(batchToSend.length);
+        this.retryCount = 0;
+      }
+    } finally {
+      this.isSending = false;
+      if (this.queue.length > 0 && this.retryCount === 0) {
+        this.scheduleSend();
+      }
+    }
+  }
+}
+// src/formatters/syslogFormatter.ts
+var SYSLOG_SEVERITY = {
+  [0 /* ERROR */]: 3,
+  [1 /* WARN */]: 4,
+  [2 /* AUDIT */]: 5,
+  [3 /* INFO */]: 6,
+  [4 /* HTTP */]: 6,
+  [5 /* DEBUG */]: 7,
+  [6 /* VERBOSE */]: 7,
+  [7 /* SILLY */]: 7
+};
+function formatRFC3164(entry, facility, appName, pid) {
+  const severity = SYSLOG_SEVERITY[entry.level];
+  const priority = facility << 3 | severity;
+  const timestamp = new Date(entry.timestamp).toLocaleString("en-US", {
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).replace(/,/, "").replace(" at ", " ");
+  const hostname = __require("os").hostname();
+  const msg = entry.metadata ? `${entry.message} ${JSON.stringify(entry.metadata)}` : entry.message;
+  return `<${priority}>${timestamp} ${hostname} ${appName}[${pid}]: ${msg}`;
+}
+function formatRFC5424(entry, facility, appName, pid) {
+  const severity = SYSLOG_SEVERITY[entry.level];
+  const priority = facility << 3 | severity;
+  const timestamp = new Date(entry.timestamp).toISOString();
+  const hostname = __require("os").hostname();
+  const msgId = "-";
+  const structuredData = entry.metadata ? `[example@1 ${Object.entries(entry.metadata).map(([key, val]) => `${key}="${val}"`).join(" ")}]` : "-";
+  return `<${priority}>1 ${timestamp} ${hostname} ${appName} ${pid} ${msgId} ${structuredData} ${entry.message}`;
+}
+function formatSyslogMessage(entry, config) {
+  const facility = config.facility ?? 1;
+  const appName = config.appName ?? "node";
+  const pid = config.pid ?? process.pid;
+  const protocolVersion = config.protocolVersion ?? 5424;
+  return protocolVersion === 3164 ? formatRFC3164(entry, facility, appName, pid) : formatRFC5424(entry, facility, appName, pid);
+}
+
+// src/transports/syslogTransport.ts
+import { createSocket, Socket } from "dgram";
+import { Socket as NetSocket } from "net";
+import { connect as tlsConnect } from "tls";
+
+class SyslogTransport {
+  socket = null;
+  queue = [];
+  isConnecting = false;
+  retryCount = 0;
+  retryBaseDelay;
+  maxQueueSize;
+  debug;
+  reconnectTimer = null;
+  config;
+  constructor(config = {}) {
+    this.maxQueueSize = config.maxQueueSize ?? 1000;
+    this.retryBaseDelay = config.retryBaseDelay ?? 1000;
+    this.debug = config.debug ?? false;
+    this.config = {
+      host: config.host ?? "localhost",
+      port: config.port ?? 514,
+      protocol: config.protocol ?? "udp",
+      facility: config.facility ?? 1,
+      appName: config.appName ?? "node",
+      pid: config.pid ?? process.pid,
+      protocolVersion: config.protocolVersion ?? 5424,
+      tlsOptions: config.tlsOptions || {}
+    };
+    this.initializeSocket();
+  }
+  initializeSocket() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      if (!("destroy" in this.socket)) {
+        this.socket.close();
+      } else {
+        this.socket.destroy();
+      }
+    }
+    if (this.config.protocol === "udp") {
+      this.initializeUdpSocket();
+    } else if (this.config.protocol === "tcp") {
+      this.initializeTcpSocket();
+    } else if (this.config.protocol === "tcp-tls") {
+      this.initializeTlsSocket();
+    }
+  }
+  initializeUdpSocket() {
+    this.socket = createSocket("udp4");
+    this.socket.on("error", (err) => {
+      if (this.debug)
+        console.error("Syslog UDP error:", err);
+      this.handleSocketError();
+    });
+    this.socket.on("close", () => {
+      if (this.debug)
+        console.log("Syslog UDP socket closed");
+    });
+  }
+  initializeTcpSocket() {
+    this.socket = new NetSocket;
+    this.setupTcpSocketEvents();
+    this.connectTcpSocket();
+  }
+  initializeTlsSocket() {
+    const tlsOptions = {
+      host: this.config.host,
+      port: this.config.port,
+      ...this.config.tlsOptions
+    };
+    this.socket = tlsConnect(tlsOptions, () => {
+      if (this.debug)
+        console.log("Syslog TLS connection established");
+      this.retryCount = 0;
+      this.flushQueue();
+    });
+    this.setupTcpSocketEvents();
+  }
+  setupTcpSocketEvents() {
+    if (!this.socket)
+      return;
+    this.socket.on("error", (err) => {
+      if (this.debug)
+        console.error("Syslog TCP/TLS error:", err);
+      this.handleSocketError();
+    });
+    this.socket.on("close", () => {
+      if (this.debug)
+        console.log("Syslog TCP/TLS connection closed");
+      this.handleSocketError();
+    });
+    this.socket.on("end", () => {
+      if (this.debug)
+        console.log("Syslog TCP/TLS connection ended");
+    });
+  }
+  connectTcpSocket() {
+    if (this.isConnecting || !(this.socket instanceof NetSocket))
+      return;
+    this.isConnecting = true;
+    this.socket.connect(this.config.port, this.config.host, () => {
+      if (this.debug)
+        console.log("Syslog TCP connection established");
+      this.isConnecting = false;
+      this.retryCount = 0;
+      this.flushQueue();
+    });
+  }
+  handleSocketError() {
+    if (this.reconnectTimer)
+      return;
+    this.socket = null;
+    this.isConnecting = false;
+    this.retryCount++;
+    const delay = Math.min(this.retryBaseDelay * Math.pow(2, this.retryCount - 1), 30000);
+    if (this.debug)
+      console.log(`Attempting to reconnect in ${delay}ms (attempt ${this.retryCount})`);
+    this.reconnectTimer = setTimeout(() => {
+      this.initializeSocket();
+    }, delay);
+  }
+  flushQueue() {
+    if (!this.socket || this.queue.length === 0)
+      return;
+    while (this.queue.length > 0) {
+      const message = this.queue.shift();
+      if (message) {
+        this.sendMessage(message);
+      }
+    }
+  }
+  sendMessage(message) {
+    if (!this.socket) {
+      this.queue.unshift(message);
+      return;
+    }
+    try {
+      if (this.socket instanceof Socket) {
+        this.socket.send(message, this.config.port, this.config.host, (err) => {
+          if (err && this.debug)
+            console.error("Syslog UDP send error:", err);
+        });
+      } else {
+        this.socket.write(message + `
+`, (err) => {
+          if (err && this.debug)
+            console.error("Syslog TCP/TLS send error:", err);
+        });
+      }
+    } catch (err) {
+      if (this.debug)
+        console.error("Syslog send error:", err);
+      this.queue.unshift(message);
     }
   }
+  log(entry) {
+    const message = formatSyslogMessage(entry, this.config);
+    if (this.queue.length >= this.maxQueueSize) {
+      if (this.debug)
+        console.warn("Syslog queue full - dropping oldest message");
+      this.queue.shift();
+    }
+    this.queue.push(message);
+    if (this.socket && !this.isConnecting) {
+      this.flushQueue();
+    } else if (!this.socket && !this.isConnecting) {}
+  }
+  close() {
+    return new Promise((resolve) => {
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+      if (!this.socket) {
+        resolve();
+        return;
+      }
+      const handleClose = () => {
+        resolve();
+      };
+      if ("destroy" in this.socket) {
+        this.socket.destroy();
+        process.nextTick(handleClose);
+      } else {
+        this.socket.close(handleClose);
+      }
+    });
+  }
 }
 export {
+  SyslogTransport,
   NDJsonTransport,
   LokiTransport,
   Logger,

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@rabbit-company/logger",
-	"version": "5.1.0",
+	"version": "5.3.0",
 	"description": "A simple and lightweight logger",
-	"main": "./module/index.js",
+	"main": "./module/logger.js",
 	"type": "module",
 	"homepage": "https://github.com/Rabbit-Company/Logger-JS",
 	"funding": "https://rabbit-company.com/donation",
@@ -35,9 +35,8 @@
 		"loki"
 	],
 	"devDependencies": {
-		"@types/bun": "^1.2.10",
-		"bun-plugin-dts": "^0.3.0",
-		"@rabbit-company/logger": "^4.0.0"
+		"@types/bun": "latest",
+		"bun-plugin-dts": "^0.3.0"
 	},
 	"peerDependencies": {
 		"typescript": "^5.5.4"