@loglayer/transport-log-file-rotation 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,393 @@
+import { LoggerlessTransportConfig, LoggerlessTransport, LogLayerTransportParams } from '@loglayer/transport';
+
+interface LogFileRotationCallbacks {
+    /**
+     * Called when a log file is rotated
+     * @param oldFile - The path to the old log file
+     * @param newFile - The path to the new log file
+     */
+    onRotate?: (oldFile: string, newFile: string) => void;
+    /**
+     * Called when a new log file is created
+     * @param newFile - The path to the new log file
+     */
+    onNew?: (newFile: string) => void;
+    /**
+     * Called when a log file is opened
+     */
+    onOpen?: () => void;
+    /**
+     * Called when a log file is closed
+     */
+    onClose?: () => void;
+    /**
+     * Called when an error occurs
+     * @param error - The error that occurred
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Called when the stream is finished
+     */
+    onFinish?: () => void;
+    /**
+     * Called when a log file is removed due to retention policy
+     * @param info - Information about the removed log file
+     */
+    onLogRemoved?: (info: {
+        date: number;
+        name: string;
+        hash: string;
+    }) => void;
+}
+interface LogFileRotationFieldNames {
+    /**
+     * Field name for the log level
+     * @default "level"
+     */
+    level?: string;
+    /**
+     * Field name for the log message
+     * @default "message"
+     */
+    message?: string;
+    /**
+     * Field name for the timestamp
+     * @default "timestamp"
+     */
+    timestamp?: string;
+}
+interface LogFileRotationLevelMap {
+    /**
+     * Mapping for the 'fatal' log level
+     * @example 60 or "FATAL"
+     */
+    fatal?: string | number;
+    /**
+     * Mapping for the 'error' log level
+     * @example 50 or "ERROR"
+     */
+    error?: string | number;
+    /**
+     * Mapping for the 'warn' log level
+     * @example 40 or "WARN"
+     */
+    warn?: string | number;
+    /**
+     * Mapping for the 'info' log level
+     * @example 30 or "INFO"
+     */
+    info?: string | number;
+    /**
+     * Mapping for the 'debug' log level
+     * @example 20 or "DEBUG"
+     */
+    debug?: string | number;
+    /**
+     * Mapping for the 'trace' log level
+     * @example 10 or "TRACE"
+     */
+    trace?: string | number;
+}
+interface LogFileRotationBatchConfig {
+    /**
+     * Maximum number of log entries to queue before writing.
+     * Default: 1000
+     */
+    size?: number;
+    /**
+     * Maximum time in milliseconds to wait before writing queued logs.
+     * Default: 5000 (5 seconds)
+     */
+    timeout?: number;
+}
+interface LogFileRotationTransportConfig extends LoggerlessTransportConfig {
+    /**
+     * The filename pattern to use for the log files.
+     * Supports date format using numerical values.
+     * Example: "./logs/application-%DATE%.log"
+     */
+    filename: string;
+    /**
+     * The frequency of rotation. Can be:
+     * - 'daily' for daily rotation
+     * - 'date' for rotation on date format change
+     * - '[1-30]m' for rotation every X minutes
+     * - '[1-12]h' for rotation every X hours
+     */
+    frequency?: string;
+    /**
+     * The date format to use in the filename.
+     * Uses single characters for each date component:
+     * - 'Y' for full year
+     * - 'M' for month
+     * - 'D' for day
+     * - 'H' for hour
+     * - 'm' for minutes
+     * - 's' for seconds
+     *
+     * Common patterns:
+     * - For daily rotation: use "YMD" (creates files like app-20240117.log)
+     * - For hourly/minute rotation: use "YMDHm" (creates files like app-202401171430.log)
+     *
+     * @default "YMD"
+     */
+    dateFormat?: string;
+    /**
+     * The size at which to rotate.
+     * Examples: "10M", "100K", "100B"
+     * If frequency is specified, this will be ignored.
+     */
+    size?: string;
+    /**
+     * Maximum number of logs to keep.
+     * Can be a number of files or days (e.g., "10d" for 10 days)
+     */
+    maxLogs?: string | number;
+    /**
+     * Location to store the log audit file.
+     * If not set, it will be stored in the root of the application.
+     */
+    auditFile?: string;
+    /**
+     * File extension to be appended to the filename.
+     * Useful when using size restrictions as the rotation adds a count at the end.
+     */
+    extension?: string;
+    /**
+     * Create a tailable symlink to the current active log file.
+     * Default: false
+     */
+    createSymlink?: boolean;
+    /**
+     * Name to use when creating the symbolic link.
+     * Default: 'current.log'
+     */
+    symlinkName?: string;
+    /**
+     * Use UTC time for date in filename.
+     * Default: false
+     */
+    utc?: boolean;
+    /**
+     * Use specified hashing algorithm for audit.
+     * Default: 'md5'
+     * Use 'sha256' for FIPS compliance.
+     */
+    auditHashType?: "md5" | "sha256";
+    /**
+     * File mode to be used when creating log files.
+     * Default: 0o640 (user read/write, group read, others none)
+     */
+    fileMode?: number;
+    /**
+     * Options passed to the file stream.
+     * See: https://nodejs.org/api/fs.html#fs_fs_createwritestream_path_options
+     */
+    fileOptions?: {
+        flags?: string;
+        encoding?: string;
+        mode?: number;
+    };
+    /**
+     * Event callbacks for various file stream events
+     */
+    callbacks?: LogFileRotationCallbacks;
+    /**
+     * Custom field names for the log entry JSON
+     * Default: { level: "level", message: "message", data: "data", timestamp: "timestamp" }
+     */
+    fieldNames?: LogFileRotationFieldNames;
+    /**
+     * Delimiter between log entries.
+     * Default: "\n"
+     */
+    delimiter?: string;
+    /**
+     * Custom function to generate timestamps for log entries.
+     * Can return either a string (e.g., ISO string) or a number (e.g., Unix timestamp)
+     * If not provided, defaults to new Date().toISOString()
+     */
+    timestampFn?: () => string | number;
+    /**
+     * Custom mapping for log levels.
+     * Each log level can be mapped to either a string or number.
+     * Example: { error: 50, warn: 40, info: 30, debug: 20, trace: 10, fatal: 60 }
+     * Example: { error: "ERROR", warn: "WARN", info: "INFO", debug: "DEBUG", trace: "TRACE", fatal: "FATAL" }
+     */
+    levelMap?: LogFileRotationLevelMap;
+    /**
+     * Whether to compress rotated log files using gzip.
+     * When enabled, rotated files will be compressed with .gz extension.
+     * Default: false
+     */
+    compressOnRotate?: boolean;
+    /**
+     * Whether to enable verbose mode in the underlying file-stream-rotator.
+     * When enabled, the rotator will log detailed information about its operations.
+     * Default: false
+     */
+    verbose?: boolean;
+    /**
+     * Batch processing configuration.
+     * If defined, batch processing will be enabled.
+     * When batching is enabled, logs are queued in memory and written to disk in batches.
+     * Queued logs are automatically flushed in the following situations:
+     * - When the batch size is reached
+     * - When the batch timeout is reached
+     * - When the transport is disposed
+     * - When the process exits (including SIGINT and SIGTERM signals)
+     */
+    batch?: LogFileRotationBatchConfig;
+}
+/**
+ * A transport that writes logs to rotating files with support for time-based and size-based rotation.
+ * Features include:
+ * - Automatic log file rotation based on time (hourly, daily) or size
+ * - Support for date patterns in filenames using numerical values (YYYY, MM, DD, etc.)
+ * - Size-based rotation with support for KB, MB, and GB units
+ * - Compression of rotated log files using gzip
+ * - Maximum file count or age-based retention
+ * - Automatic cleanup of old log files
+ * - Batch processing of logs for improved performance
+ * - Safe handling of process termination signals
+ *
+ * Each instance must have a unique filename to prevent race conditions.
+ * If you need multiple loggers to write to the same file, share the same transport instance between them.
+ */
+declare class LogFileRotationTransport extends LoggerlessTransport implements Disposable {
+    /** Registry of active filenames to prevent multiple transports writing to the same file */
+    private static activeFilenames;
+    /** The current write stream for the log file */
+    private stream;
+    /** Custom field names for log entries */
+    private fieldNames;
+    /** Delimiter between log entries */
+    private delimiter;
+    /** Function to generate timestamps for log entries */
+    private timestampFn;
+    /** Custom mapping for log levels */
+    private levelMap;
+    /** Whether to compress rotated files */
+    private compressOnRotate;
+    /** Whether a file is currently being compressed */
+    private isCompressing;
+    /** The base filename pattern for log files */
+    private filename;
+    /** Whether batch processing is enabled */
+    private batchEnabled;
+    /** Maximum number of log entries to queue before writing */
+    private batchSize;
+    /** Maximum time in milliseconds to wait before writing queued logs */
+    private batchTimeout;
+    /** Queue of log entries waiting to be written */
+    private batchQueue;
+    /** Timer for batch flush timeout */
+    private batchTimer;
+    /** Whether the transport is being disposed */
+    private isDisposing;
+    /** Event callbacks for various file stream events */
+    private callbacks?;
+    /** Frequency of rotation (daily, hourly, etc.) */
+    private frequency?;
+    /** Whether to enable verbose mode */
+    private verbose?;
+    /** Date format for filename patterns */
+    private dateFormat?;
+    /** Size threshold for rotation */
+    private size?;
+    /** Maximum number of log files to keep */
+    private maxLogs?;
+    /** Path to the audit file */
+    private auditFile?;
+    /** File extension for log files */
+    private extension?;
+    /** Whether to create a symlink to current log */
+    private createSymlink?;
+    /** Name of the symlink file */
+    private symlinkName?;
+    /** Whether to use UTC time in filenames */
+    private utc?;
+    /** Hash algorithm for audit file */
+    private auditHashType?;
+    /** Options for file streams */
+    private fileOptions?;
+    /** File mode to be used when creating log files */
+    private fileMode?;
+    /**
+     * Generates the options for FileStreamRotator consistently across the transport
+     * @returns FileStreamRotatorOptions object
+     * @private
+     */
+    private getRotatorOptions;
+    /**
+     * Creates a new LogFileRotationTransport instance.
+     * @param params - Configuration options for the transport
+     * @throws {Error} If the filename is already in use by another transport instance
+     */
+    constructor(params: LogFileRotationTransportConfig);
+    /**
+     * Initializes the write stream and sets up event listeners.
+     * This is called either immediately if batching is disabled,
+     * or lazily when the first batch needs to be written if batching is enabled.
+     * @param options - Options for the file stream rotator
+     * @private
+     */
+    private initStream;
+    /**
+     * Generates a unique path for a compressed log file.
+     * If a file with .gz extension already exists, appends timestamp and counter.
+     * @param filePath - The original log file path
+     * @returns The unique path for the compressed file
+     * @private
+     */
+    private getUniqueCompressedFilePath;
+    /**
+     * Compresses a log file using gzip.
+     * @param filePath - Path to the file to compress
+     * @returns Path to the compressed file
+     * @private
+     */
+    private compressFile;
+    /**
+     * Flushes queued log entries to disk asynchronously.
+     * This is used for normal batch processing operations.
+     * @private
+     */
+    private flush;
+    /**
+     * Synchronously flush logs to disk.
+     * This is used during process termination (SIGINT/SIGTERM) to ensure logs are written
+     * before the process exits. This method uses synchronous file I/O to guarantee that
+     * logs are written even during abrupt process termination.
+     * @private
+     */
+    private flushSync;
+    /**
+     * Schedules a batch flush operation.
+     * This creates a timer that will flush the batch after the configured timeout.
+     * The timer is unref'd to prevent keeping the process alive.
+     * @private
+     */
+    private scheduleBatchFlush;
+    /**
+     * Processes and writes a log entry.
+     * If batching is enabled, the entry is queued and written based on batch settings.
+     * If batching is disabled, the entry is written immediately.
+     * @param params - The log entry parameters
+     * @returns The original messages array
+     */
+    shipToLogger({ logLevel, messages, data, hasData }: LogLayerTransportParams): any[];
+    /**
+     * Disposes of the transport, cleaning up resources and flushing any remaining logs.
+     * This method:
+     * 1. Prevents new batch flushes from being scheduled
+     * 2. Cancels any pending batch flush
+     * 3. Flushes any remaining logs
+     * 4. Waits for any in-progress compression to complete
+     * 5. Closes the write stream
+     * 6. Removes the filename from the registry
+     */
+    [Symbol.dispose](): void;
+}
+
+export { type LogFileRotationBatchConfig, type LogFileRotationCallbacks, type LogFileRotationFieldNames, type LogFileRotationLevelMap, LogFileRotationTransport, type LogFileRotationTransportConfig };