ReadEOF

A high-performance, memory-efficient library to read large files backward (line-by-line). Zero dependencies.

Features

• Fast file reading from the end without loading entire file into memory
• Memory efficient using configurable buffer sizes
• Supports various encodings
• Real-time file tailing (like tail -f) with streaming support
• Automatic handling of file truncation/rotation

Installation

npm install readeof

Usage

Basic Example

import { readeof } from 'readeof';

// Read last 10 lines from log file
const lastLines = await readeof('/var/log/app.log', 10);
console.log(lastLines);

Reading Recent Logs

import { readeof } from 'readeof';

// Read last 50 lines for debugging
const recentLogs = await readeof('./app.log', 50);
console.log(recentLogs);

Custom Encoding

import { readeof } from 'readeof';

// Read file with latin1 encoding
const content = await readeof('./data.txt', 20, { encoding: 'latin1' });

Custom Buffer Size

import { readeof } from 'readeof';

// Use 64KB buffer for very large files
const content = await readeof('./huge-log.log', 100, {
  encoding: 'utf8',
  bufferSize: 64 * 1024,
});

Real-time Log Streaming (tail -f)

Stream new lines as they are appended to the file. First reads the last N lines, then continues watching for new content.

import { readeof } from 'readeof';

// Stream with AbortController for manual control
const controller = new AbortController();

for await (const line of readeof('/var/log/app.log', 10, {
  enabled: true,
  signal: controller.signal,
})) {
  console.log(line);

  // Stop streaming when needed
  if (line.includes('SHUTDOWN')) {
    controller.abort();
  }
}

Streaming with Timeout

import { readeof } from 'readeof';

// Stream for 30 seconds then stop automatically
for await (const line of readeof('/var/log/app.log', 10, {
  enabled: true,
  signal: AbortSignal.timeout(30_000),
})) {
  console.log(line);
}

Streaming with Custom Poll Interval

import { readeof } from 'readeof';

// Check for new content every 500ms instead of default 1000ms
for await (const line of readeof('/var/log/app.log', 10, {
  enabled: true,
  pollInterval: 500,
  signal: AbortSignal.timeout(60_000),
})) {
  console.log(line);
}

Error Analysis

import { readeof } from 'readeof';

async function findRecentErrors(logPath: string) {
  const recentLogs = await readeof(logPath, 1000);
  const errors = recentLogs
    .split('\n')
    .filter(line => line.includes('ERROR'));
  
  console.log(`Found ${errors.length} errors in last 1000 lines`);
}

API Reference

readeof(filePath, maxLines, options?)

Reads the last N lines from a file efficiently.

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | filePath | string | Path to the file to read from | | maxLines | number | Total lines to read from the end of the file | | options | ReadOptions \| StreamOptions | Optional configuration options |

ReadOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | encoding | BufferEncoding | 'utf8' | File encoding | | bufferSize | number | 16384 | Buffer size for reading (16KB) |

StreamOptions (extends ReadOptions)

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | - | Enable streaming mode | | pollInterval | number | 1000 | Polling interval in milliseconds | | signal | AbortSignal | - | Signal to stop streaming |

Returns

• Without streaming: Promise<string> - The last N lines as a single string
• With streaming: AsyncGenerator<string> - Yields each line as it appears

License

See LICENSE file for details.

Author

Ashary Vermaysha ([email protected])