fengxinming/rolling-write-stream

A high-performance Node.js log rolling library supporting size-based and date-based rolling, with compression backup and multi-process safety.

rolling-write-stream

A high-performance Node.js log rolling library supporting size-based and date-based rolling, with compression backup and multi-process safety.

中文 | English

Features

• 📁 Dual Mode Rolling: Support automatic rolling by file size or date
• 🔒 Multi-process Safe: Optional file lock to prevent concurrent writes
• 🗜️ Compression Backup: Gzip compression for historical logs
• ⚡ High-performance: Async I/O and backpressure management
• 📊 Flexible Configuration: Customizable rolling strategy, filename format and sync policy

Installation

npm install rolling-log-stream

Quick Start

Rolling by Size

import { FileStream } from 'rolling-log-stream';

const logger = new FileStream('./logs/app.log', {
  maxSize: 1024 * 1024, // Roll when reaching 1MB
  backups: 5,           // Keep 5 backups
  compress: true        // Compress old files
});

logger.write('This is a log entry\n');

Rolling by Date

import { DateFileStream } from 'rolling-log-stream';

const dailyLogger = new DateFileStream('./logs/daily.log', {
  pattern: 'YYYY-MM-DD',  // Daily rolling
  maxSize: 512 * 1024,    // 512KB per file
  backups: 7              // Keep 7 days of logs
});

dailyLogger.write(`[${new Date().toISOString()}] System startup\n`);

Configuration Options

Common Options (RollingOptions)

Parameter	Type	Default	Description
maxSize	number	0	File size threshold (bytes) for rolling (0 to disable)
backups	number	1	Number of backup files to retain
compress	boolean	false	Enable compression for backups
encoding	string	'utf8'	File encoding
keepFileExt	boolean	false	Keep file extension in backup names
fileNameSep	string	'.'	Filename separator
useLock	boolean	false	Enable multi-process file lock
syncThreshold	number	0	Data threshold (bytes) for forced sync
syncInterval	number	10000	Time interval (ms) for periodic sync

Date Rolling Options (DateRollingOptions)

Parameter	Type	Default	Description
pattern	string	'YYYY-MM-DD'	Date format (using date-manip syntax)

API Reference

FileStream

• new FileStream(filePath: string, options?: Partial<RollingOptions>)
• Methods:
  • write(chunk: string|Buffer): Promise<void>
  • end(): Promise<void>

DateFileStream

• new DateFileStream(filePath: string, options?: Partial<DateRollingOptions>)
• Methods same as FileStream

Advanced Examples

Production Configuration

const prodLogger = new DateFileStream('/var/log/myapp/prod.log', {
  pattern: 'YYYYMMDD',
  maxSize: 50 * 1024 * 1024,  // 50MB per file
  backups: 9,                 // Keep 9 daily backups
  compress: true,
  useLock: true,              // Enable file lock
  syncThreshold: 1024 * 1024  // Force sync every 1MB
});

Custom Filename Format

const customLogger = new FileStream('./logs/data.log', {
  keepFileExt: true,          // Generate names like data.1.log
  fileNameSep: '_',           // Use underscore separator
  backups: 10
});

Running Tests

Unit Tests

npm test

Performance Tests

npm run stress

Contribution Guide

Contributions are welcome via Issues and Pull Requests!
Development workflow:

1. Fork the repository
2. Create feature/fix branches (e.g., feat/xxx or fix/xxx)
3. Commit code with tests
4. Create Pull Request

License

MIT License