@logone/adapter-file

@logone/adapter-file

A Logone adapter for outputting logs to files with rotation capabilities.

Features

• File log output with JSON format
• File rotation (size-based and time-based)
• Customizable output format
• Multiple encoding support
• Timestamp-based file naming

Installation

npm install @logone/adapter-file

Usage

Basic Usage

import { createAdapter } from '@logone/adapter-file'
import { createLogger } from '@logone/core'

const adapter = createAdapter({
  filepath: './logs/app.log'
})

const logger = createLogger({
  adapters: adapter
})

logger.info('Hello, world!')

File Rotation

Size-based Rotation

const adapter = createAdapter({
  filepath: './logs/app.log',
  maxFileSize: 10 * 1024 * 1024, // 10MB
  rotateFileCount: 5 // app.log, app.1.log, app.2.log, app.3.log, app.4.log
})

Time-based Rotation

// Daily rotation
const dailyAdapter = createAdapter({
  filepath: './logs/app.log',
  rotationFrequency: 'daily',
  timestampFormat: 'YYYY-MM-DD' // app.2024-01-15.log
})

// Hourly rotation
const hourlyAdapter = createAdapter({
  filepath: './logs/app.log',
  rotationFrequency: 'hourly',
  timestampFormat: 'YYYY-MM-DD_HH' // app.2024-01-15_14.log
})

// Minutely rotation
const minutelyAdapter = createAdapter({
  filepath: './logs/app.log',
  rotationFrequency: 'minutely',
  timestampFormat: 'YYYY-MM-DD_HH-mm' // app.2024-01-15_14-30.log
})

Configuration Options

const adapter = createAdapter({
  filepath: './logs/app.log',
  maxFileSize: 5 * 1024 * 1024, // 5MB
  rotateFileCount: 3,
  append: true, // Append to file (default: true)
  encoding: 'utf-8' // File encoding (default: 'utf-8')
})

API

FileAdapterOptions

Property	Type	Default	Description
filepath	string	-	Output file path (required)
maxFileSize	number	Infinity	Maximum file size in bytes
rotateFileCount	number	5	Number of rotation files to keep
append	boolean	true	Whether to append to existing file
encoding	BufferEncoding	'utf-8'	File encoding
rotationFrequency	'daily' | 'hourly' | 'minutely'	undefined	Time-based rotation frequency
timestampFormat	string	'YYYY-MM-DD'	Timestamp format pattern

Rotation Strategies

Size-based Rotation

When maxFileSize is specified, files are automatically rotated when they exceed the specified size.

Example: When app.log reaches 5MB:

• app.log → renamed to app.1.log
• New app.log is created

Use rotateFileCount to specify the number of files to keep. Older files are automatically deleted.

Time-based Rotation

When rotationFrequency is specified, new files are created at specified intervals:

• daily: Daily rotation (new file when date changes)
• hourly: Hourly rotation (new file when hour changes)
• minutely: Minutely rotation (new file when minute changes)

Timestamp Format

Available format tokens for time-based rotation:

• YYYY: Year (4 digits)
• MM: Month (2 digits, zero-padded)
• DD: Day (2 digits, zero-padded)
• HH: Hour (2 digits, zero-padded, 24-hour format)
• mm: Minute (2 digits, zero-padded)
• ss: Second (2 digits, zero-padded)