@rabbit-company/logger 5.0.0 → 5.2.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, INFO, HTTP, VERBOSE, DEBUG, 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, and Grafana Loki
+- **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, Bun and modern browsers
+- **Type-safe**: Full TypeScript definitions included
 
 ## Installation 📦
 
@@ -38,14 +35,74 @@ 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:
+
+### Available Placeholders
+
+#### UTC Formats:
+
+- `{iso}`: Full ISO-8601 (2023-11-15T14:30:45.123Z)
+- `{datetime}`: Simplified (2023-11-15 14:30:45)
+- `{date}`: Date only (2023-11-15)
+- `{time}`: Time only (14:30:45)
+- `{utc}`: UTC string (Wed, 15 Nov 2023 14:30:45 GMT)
+- `{ms}`: Milliseconds since epoch
+
+#### Local Time Formats:
+
+- `{datetime-local}`: Local datetime (2023-11-15 14:30:45)
+- `{date-local}`: Local date only (2023-11-15)
+- `{time-local}`: Local time only (14:30:45)
+- `{full-local}`: Complete local string with timezone
+
+#### Log Content:
+
+- `{type}`: Log level (INFO, ERROR, etc.)
+- `{message}`: The log message
+
+```js
+import { ConsoleTransport } from "@rabbit-company/logger";
+
+// Custom format examples
+new ConsoleTransport("[{datetime-local}] {type} {message}");
+new ConsoleTransport("{time} | {type} | {message}", false);
+new ConsoleTransport("EPOCH:{ms} {message}");
 ```
 
 ## Transports 🚚
@@ -58,7 +115,7 @@ import { ConsoleTransport } from "@rabbit-company/logger";
 const logger = new Logger({
 	transports: [
 		new ConsoleTransport(
-			"[{date}] {type} {message}", // Custom format
+			"[{time-local}] {type} {message}", // Custom format
 			true // Enable colors
 		),
 	],
@@ -79,133 +136,35 @@ 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
-
-```js
-enum Levels {
-  ERROR,    // Critical errors
-  WARN,     // Warnings
-  INFO,     // Informational messages
-  HTTP,     // HTTP-related logs
-  VERBOSE,  // Verbose debugging
-  DEBUG,    // Debug messages
-  SILLY     // Very low-level logs
-}
-```
-
-### Logging Methods
-
-```js
-logger.error(message: string, metadata?: object): void
-logger.warn(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
-```
-
-### 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]];
-}
-```
+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

@@ -45,46 +45,88 @@ export declare const enum Colors {
  *
  * The levels are ordered from most important (ERROR) to least important (SILLY).
  * When setting a log level, only messages of that level or higher will be emitted.
+ *
+ * @example
+ * // Set logger to display DEBUG level and above
+ * logger.setLevel(Levels.DEBUG);
  */
 export declare enum Levels {
 	/**
 	 * Error level. Indicates critical issues that require immediate attention.
 	 * Use for unrecoverable errors that prevent normal operation.
+	 * @example
+	 * logger.error("Database connection failed");
 	 */
 	ERROR = 0,
 	/**
 	 * Warning level. Indicates potential issues or noteworthy conditions.
 	 * Use for recoverable issues that don't prevent normal operation.
+	 * @example
+	 * logger.warn("High memory usage detected");
 	 */
 	WARN = 1,
+	/**
+	 * Audit level. For security-sensitive operations and compliance logging.
+	 * Use for tracking authentication, authorization, and sensitive data access.
+	 * @example
+	 * logger.audit("User permissions changed", { user: "admin", changes: [...] });
+	 */
+	AUDIT = 2,
 	/**
 	 * Informational level. Provides general information about the application's state.
 	 * Use for normal operational messages that highlight progress.
+	 * @example
+	 * logger.info("Application started on port 3000");
 	 */
-	INFO = 2,
+	INFO = 3,
 	/**
 	 * HTTP-related level. Logs HTTP requests and responses.
 	 * Use for tracking HTTP API calls and their status.
+	 * @example
+	 * logger.http("GET /api/users 200 45ms");
 	 */
-	HTTP = 3,
-	/**
-	 * Verbose level. Provides detailed information for in-depth analysis.
-	 * Use for detailed operational logs that are typically only needed during debugging.
-	 */
-	VERBOSE = 4,
+	HTTP = 4,
 	/**
 	 * Debug level. Provides detailed context for debugging purposes.
 	 * Use for extended debugging information during development.
+	 * @example
+	 * logger.debug("Database query", { query: "...", duration: "120ms" });
 	 */
 	DEBUG = 5,
+	/**
+	 * Verbose level. Provides detailed information for in-depth analysis.
+	 * Use for detailed operational logs that are typically only needed during debugging.
+	 * @example
+	 * logger.verbose("Cache update cycle completed", { entries: 1423 });
+	 */
+	VERBOSE = 6,
 	/**
 	 * Silly level. Logs very low-level messages.
 	 * Use for extremely verbose logging messages.
+	 * @example
+	 * logger.silly("Iteration 14563 completed");
 	 */
-	SILLY = 6
+	SILLY = 7
 }
 /**
  * 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 */
@@ -97,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;
 }
 /**
@@ -216,126 +376,382 @@ export declare class Logger {
 	 */
 	private processEntry;
 	/**
-	 * Logs an error message
+	 * Logs an error message (highest severity)
 	 * @param message The error message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.error("Database connection failed", { error: error.stack });
 	 */
 	error(message: string, metadata?: Record<string, any>): void;
 	/**
 	 * Logs a warning message
 	 * @param message The warning message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.warn("High memory usage detected", { usage: "85%" });
 	 */
 	warn(message: string, metadata?: Record<string, any>): void;
+	/**
+	 * Logs security-sensitive audit events
+	 * @param message The audit message
+	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.audit("User permissions modified", {
+	 *   actor: "admin@example.com",
+	 *   action: "role_change",
+	 *   target: "user:1234"
+	 * });
+	 */
+	audit(message: string, metadata?: Record<string, any>): void;
 	/**
 	 * Logs an informational message
 	 * @param message The info message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.info("Server started", { port: 3000, env: "production" });
 	 */
 	info(message: string, metadata?: Record<string, any>): void;
 	/**
-	 * Logs an HTTP-related message
+	 * Logs HTTP-related messages
 	 * @param message The HTTP message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.http("Request completed", {
+	 *   method: "GET",
+	 *   path: "/api/users",
+	 *   status: 200,
+	 *   duration: "45ms"
+	 * });
 	 */
 	http(message: string, metadata?: Record<string, any>): void;
 	/**
-	 * Logs a verbose message
-	 * @param message The verbose message
+	 * Logs debug information (for development environments)
+	 * @param message The debug message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.debug("Database query", {
+	 *   query: "SELECT * FROM users",
+	 *   parameters: { limit: 50 }
+	 * });
 	 */
-	verbose(message: string, metadata?: Record<string, any>): void;
+	debug(message: string, metadata?: Record<string, any>): void;
 	/**
-	 * Logs a debug message
-	 * @param message The debug message
+	 * Logs verbose tracing information (very detailed)
+	 * @param message The verbose message
 	 * @param metadata Optional metadata object
+	 * @example
+	 * logger.verbose("Cache update cycle", {
+	 *   entriesProcessed: 1423,
+	 *   memoryUsage: "1.2MB"
+	 * });
 	 */
-	debug(message: string, metadata?: Record<string, any>): void;
+	verbose(message: string, metadata?: Record<string, any>): void;
 	/**
-	 * Logs a silly message (lowest level)
+	 * Logs extremely low-level details (lowest severity)
 	 * @param message The silly message
-	 * @param metadata Optional metadata object
+	 * @param metadata Optional metadata data
+	 * @example
+	 * logger.silly("Iteration complete", { iteration: 14563 });
 	 */
 	silly(message: string, metadata?: Record<string, any>): void;
 	/**
 	 * Adds a new transport to the logger
 	 * @param transport The transport to add
+	 * @example
+	 * logger.addTransport(new LokiTransport({ url: "http://loki:3100" }));
 	 */
 	addTransport(transport: Transport): void;
 	/**
 	 * Removes a transport from the logger
 	 * @param transport The transport to remove
+	 * @example
+	 * logger.removeTransport(consoleTransport);
 	 */
 	removeTransport(transport: Transport): void;
 	/**
 	 * Sets the minimum log level
 	 * @param level The new minimum log level
+	 * @example
+	 * // Only show errors and warnings
+	 * logger.setLevel(Levels.WARN);
 	 */
 	setLevel(level: Levels): void;
 }
 /**
- * Transport that outputs logs to the console with configurable formatting
+ * Transport that outputs logs to the console with configurable formatting and colors.
+ *
+ * Features:
+ * - Customizable output format with extensive placeholder support
+ * - ANSI color support (enabled by default)
+ * - Cross-platform compatibility (Node.js and browsers)
+ * - Lightweight and performant
+ *
+ * @example
+ * // Basic usage with default formatting
+ * const transport = new ConsoleTransport();
+ *
+ * @example
+ * // Custom format with local timestamps
+ * const transport = new ConsoleTransport(
+ *   "[{datetime-local}] {type} - {message}",
+ *   true
+ * );
  */
 export declare class ConsoleTransport implements Transport {
 	private format;
 	private colors;
 	/**
-	 * Create a ConsoleTransport instance
-	 * @param format Format string using {date}, {type}, {message} placeholders
-	 * @param colors Enable colored output
+	 * Creates a new ConsoleTransport instance
+	 * @param format Format string supporting these placeholders:
+	 *
+	 * ### Time/Date Formats
+	 * - `{iso}`: Full ISO-8601 UTC format (YYYY-MM-DDTHH:MM:SS.mmmZ)
+	 * - `{datetime}`: Simplified UTC (YYYY-MM-DD HH:MM:SS)
+	 * - `{date}`: UTC date only (YYYY-MM-DD)
+	 * - `{time}`: UTC time only (HH:MM:SS)
+	 * - `{datetime-local}`: Local datetime (YYYY-MM-DD HH:MM:SS)
+	 * - `{date-local}`: Local date only (YYYY-MM-DD)
+	 * - `{time-local}`: Local time only (HH:MM:SS)
+	 * - `{ms}`: Milliseconds since epoch
+	 *
+	 * ### Log Content
+	 * - `{type}`: Log level name (e.g., "INFO")
+	 * - `{message}`: The log message content
+	 *
+	 * @default "[{datetime-local}] {type} {message}"
+	 *
+	 * @param colors Enable ANSI color output. When disabled:
+	 *   - Improves performance in non-TTY environments
+	 *   - Removes all color formatting
+	 * @default true
+	 *
+	 * @example
+	 * // UTC format example
+	 * new ConsoleTransport("{date} {time} [{type}] {message}");
+	 *
+	 * @example
+	 * // Local time with colors disabled
+	 * new ConsoleTransport("{time-local} - {message}", false);
 	 */
 	constructor(format?: string, colors?: boolean);
 	/**
-	 * Output a log entry to the console
-	 * @param entry The log entry to output
+	 * Formats and outputs a log entry to the console.
+	 *
+	 * Applies the configured format with these features:
+	 * - All specified placeholders are replaced
+	 * - Colors are applied to level names and messages
+	 * - Timestamps are dimmed for better readability
+	 *
+	 * @param entry The log entry containing:
+	 *   - message: string - The primary log content
+	 *   - level: Levels - The severity level
+	 *   - timestamp: number - Creation time (ms since epoch)
+	 *
+	 * @example
+	 * // With all placeholder types
+	 * transport.log({
+	 *   message: "User logged in",
+	 *   level: Levels.INFO,
+	 *   timestamp: Date.now()
+	 * });
 	 */
 	log(entry: LogEntry): void;
 }
 /**
- * Transport that collects logs in NDJSON (Newline Delimited JSON) format
+ * Transport that collects logs in NDJSON (Newline Delimited JSON) format.
+ *
+ * This transport accumulates log entries in memory as NDJSON strings,
+ * which can be retrieved or cleared as needed. Useful for:
+ * - Log aggregation
+ * - Bulk exporting logs
+ * - Integration with log processing pipelines
+ *
+ * @example
+ * // Basic usage
+ * const transport = new NDJsonTransport();
+ * const logger = new Logger({ transports: [transport] });
+ *
+ * // Get logs as NDJSON string
+ * const logs = transport.getData();
+ *
+ * @example
+ * // Periodic log flushing
+ * setInterval(() => {
+ *   const logs = transport.getData();
+ *   if (logs) {
+ *     sendToServer(logs);
+ *     transport.reset();
+ *   }
+ * }, 60000);
  */
 export declare class NDJsonTransport implements Transport {
 	private data;
 	/**
-	 * Append a log entry to the NDJSON buffer
-	 * @param entry The log entry to append
+	 * Appends a log entry to the internal NDJSON buffer.
+	 *
+	 * Automatically adds newline separators between entries.
+	 *
+	 * @param entry The log entry to append. Must contain:
+	 * - message: string
+	 * - level: Levels
+	 * - timestamp: number
+	 * - metadata?: object
+	 *
+	 * @example
+	 * transport.log({
+	 *   message: "System started",
+	 *   level: Levels.INFO,
+	 *   timestamp: Date.now()
+	 * });
 	 */
 	log(entry: LogEntry): void;
 	/**
-	 * Get the accumulated NDJSON data
-	 * @returns The NDJSON formatted log data
+	 * Retrieves all accumulated logs as an NDJSON string.
+	 *
+	 * The returned string will contain one log entry per line,
+	 * with each line being a valid JSON string.
+	 *
+	 * @returns {string} NDJSON formatted log data. Returns empty string if no logs.
+	 *
+	 * @example
+	 * // Get logs for API response
+	 * app.get('/logs', (req, res) => {
+	 *   res.type('application/x-ndjson');
+	 *   res.send(transport.getData());
+	 * });
 	 */
 	getData(): string;
 	/**
-	 * Clear the accumulated log data
+	 * Clears all accumulated log data from memory.
+	 *
+	 * Typically called after successfully transmitting logs
+	 * to prevent duplicate processing.
+	 *
+	 * @example
+	 * // Clear after successful upload
+	 * if (uploadLogs(transport.getData())) {
+	 *   transport.reset();
+	 * }
 	 */
 	reset(): void;
 }
 /**
- * Transport that sends logs to a Grafana Loki server
+ * High-reliability transport for sending logs to Grafana Loki with persistent queuing.
+ *
+ * Features:
+ * - 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
+ * - Comprehensive error handling and recovery
+ *
+ * @implements {Transport}
+ *
+ * @example <caption>Basic Configuration</caption>
+ * const lokiTransport = new LokiTransport({
+ *   url: "http://localhost:3100",
+ *   labels: { app: "my-app", env: "production" }
+ * });
+ *
+ * @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" },
+ *   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;
 	/**
-	 * Create a LokiTransport instance
-	 * @param config Configuration options for Loki
-	 * @throws {Error} If URL is not provided
+	 * Creates a new LokiTransport instance
+	 * @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);
 	/**
-	 * Add a log entry to the batch (may trigger send if batch size is reached)
-	 * @param entry The log entry to send
+	 * Queues a log entry for delivery to Loki
+	 *
+	 * @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 login successful",
+	 *   level: "INFO",
+	 *   timestamp: Date.now(),
+	 *   metadata: {
+	 *     userId: "12345",
+	 *     sourceIP: "192.168.1.100",
+	 *     device: "mobile"
+	 *   }
+	 * });
 	 */
 	log(entry: LogEntry): void;
 	/**
-	 * Send 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>}
+	 *
+	 * @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;
 }

package/module/logger.js

@@ -26,38 +26,68 @@ var Levels;
 ((Levels2) => {
   Levels2[Levels2["ERROR"] = 0] = "ERROR";
   Levels2[Levels2["WARN"] = 1] = "WARN";
-  Levels2[Levels2["INFO"] = 2] = "INFO";
-  Levels2[Levels2["HTTP"] = 3] = "HTTP";
-  Levels2[Levels2["VERBOSE"] = 4] = "VERBOSE";
+  Levels2[Levels2["AUDIT"] = 2] = "AUDIT";
+  Levels2[Levels2["INFO"] = 3] = "INFO";
+  Levels2[Levels2["HTTP"] = 4] = "HTTP";
   Levels2[Levels2["DEBUG"] = 5] = "DEBUG";
-  Levels2[Levels2["SILLY"] = 6] = "SILLY";
+  Levels2[Levels2["VERBOSE"] = 6] = "VERBOSE";
+  Levels2[Levels2["SILLY"] = 7] = "SILLY";
 })(Levels ||= {});
 var LevelColors = {
   [0 /* ERROR */]: "\x1B[31m" /* RED */,
   [1 /* WARN */]: "\x1B[93m" /* BRIGHT_YELLOW */,
-  [2 /* INFO */]: "\x1B[36m" /* CYAN */,
-  [3 /* HTTP */]: "\x1B[34m" /* BLUE */,
-  [4 /* VERBOSE */]: "\x1B[34m" /* BLUE */,
-  [5 /* DEBUG */]: "\x1B[90m" /* BRIGHT_BLACK */,
-  [6 /* SILLY */]: "\x1B[90m" /* BRIGHT_BLACK */
+  [2 /* AUDIT */]: "\x1B[35m" /* MAGENTA */,
+  [3 /* INFO */]: "\x1B[36m" /* CYAN */,
+  [4 /* HTTP */]: "\x1B[34m" /* BLUE */,
+  [5 /* DEBUG */]: "\x1B[34m" /* BLUE */,
+  [6 /* VERBOSE */]: "\x1B[90m" /* BRIGHT_BLACK */,
+  [7 /* SILLY */]: "\x1B[90m" /* BRIGHT_BLACK */
 };
 // src/formatters/consoleFormatter.ts
 function formatConsoleMessage(message, logLevel, format, colorsEnabled) {
-  let type = Levels[logLevel];
-  let date = new Date().toISOString().split(".")[0].replace("T", " ");
+  const now = new Date;
+  const type = Levels[logLevel];
+  const utcFormats = {
+    "{iso}": now.toISOString(),
+    "{datetime}": now.toISOString().split(".")[0].replace("T", " "),
+    "{time}": now.toISOString().split("T")[1].split(".")[0],
+    "{date}": now.toISOString().split("T")[0],
+    "{utc}": now.toUTCString(),
+    "{ms}": now.getTime().toString()
+  };
+  const localFormats = {
+    "{datetime-local}": now.toLocaleString("sv-SE").replace(" ", "T").split(".")[0].replace("T", " "),
+    "{time-local}": now.toLocaleTimeString("sv-SE"),
+    "{date-local}": now.toLocaleDateString("sv-SE"),
+    "{full-local}": now.toString()
+  };
+  let coloredType = type;
+  let coloredMessage = message;
   if (colorsEnabled) {
-    date = "\x1B[90m" /* BRIGHT_BLACK */ + date + "\x1B[0m" /* RESET */;
-    type = "\x1B[1m" /* BOLD */ + LevelColors[logLevel] + type + "\x1B[0m" /* RESET */;
-    message = LevelColors[logLevel] + message + "\x1B[0m" /* RESET */;
+    const color = LevelColors[logLevel];
+    const colorize = (text) => "\x1B[90m" /* BRIGHT_BLACK */ + text + "\x1B[0m" /* RESET */;
+    Object.keys(utcFormats).forEach((key) => {
+      utcFormats[key] = colorize(utcFormats[key]);
+    });
+    Object.keys(localFormats).forEach((key) => {
+      localFormats[key] = colorize(localFormats[key]);
+    });
+    coloredType = "\x1B[1m" /* BOLD */ + color + type + "\x1B[0m" /* RESET */;
+    coloredMessage = color + message + "\x1B[0m" /* RESET */;
+  }
+  let output = format;
+  const allFormats = { ...utcFormats, ...localFormats };
+  for (const [placeholder, value] of Object.entries(allFormats)) {
+    output = output.replace(new RegExp(placeholder, "g"), value);
   }
-  return format.replace("{date}", date).replace("{type}", type).replace("{message}", message);
+  return output.replace(/{type}/g, coloredType).replace(/{message}/g, coloredMessage);
 }
 
 // src/transports/consoleTransport.ts
 class ConsoleTransport {
   format;
   colors;
-  constructor(format = "[{date}] {type} {message}", colors = true) {
+  constructor(format = "[{datetime-local}] {type} {message}", colors = true) {
     this.format = format;
     this.colors = colors;
   }
@@ -68,7 +98,7 @@ class ConsoleTransport {
 
 // src/logger.ts
 class Logger {
-  level = 2 /* INFO */;
+  level = 3 /* INFO */;
   transports = [new ConsoleTransport];
   constructor(config) {
     if (config?.level !== undefined) {
@@ -102,20 +132,23 @@ class Logger {
   warn(message, metadata) {
     this.processEntry(this.createLogEntry(message, 1 /* WARN */, metadata));
   }
+  audit(message, metadata) {
+    this.processEntry(this.createLogEntry(message, 2 /* AUDIT */, metadata));
+  }
   info(message, metadata) {
-    this.processEntry(this.createLogEntry(message, 2 /* INFO */, metadata));
+    this.processEntry(this.createLogEntry(message, 3 /* INFO */, metadata));
   }
   http(message, metadata) {
-    this.processEntry(this.createLogEntry(message, 3 /* HTTP */, metadata));
-  }
-  verbose(message, metadata) {
-    this.processEntry(this.createLogEntry(message, 4 /* VERBOSE */, metadata));
+    this.processEntry(this.createLogEntry(message, 4 /* HTTP */, metadata));
   }
   debug(message, metadata) {
     this.processEntry(this.createLogEntry(message, 5 /* DEBUG */, metadata));
   }
+  verbose(message, metadata) {
+    this.processEntry(this.createLogEntry(message, 6 /* VERBOSE */, metadata));
+  }
   silly(message, metadata) {
-    this.processEntry(this.createLogEntry(message, 6 /* SILLY */, metadata));
+    this.processEntry(this.createLogEntry(message, 7 /* SILLY */, metadata));
   }
   addTransport(transport) {
     this.transports.push(transport);
@@ -186,40 +219,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"
@@ -237,12 +289,38 @@ 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();
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rabbit-company/logger",
-	"version": "5.0.0",
+	"version": "5.2.0",
 	"description": "A simple and lightweight logger",
 	"main": "./module/index.js",
 	"type": "module",
@@ -31,6 +31,7 @@
 		"logger",
 		"console",
 		"ndjson",
+		"grafana",
 		"loki"
 	],
 	"devDependencies": {