n-readlines

n-readlines

Read files line-by-line, synchronously. Zero dependencies.

Reading a file line by line may seem trivial, but in Node.js there's no straightforward way to do it. Many libraries use Transform Streams which feels like overkill for such a simple task. This library uses only Node's built-in fs module to provide a clean, synchronous API.

Features

• Simple API — just next() to get the next line
• Zero dependencies — only uses Node.js built-ins
• Synchronous — no callbacks or promises to manage
• Memory efficient — reads in chunks, doesn't load entire file
• Configurable — custom chunk sizes
• TypeScript support — includes type definitions
• Cross-platform — handles LF, CRLF, and CR line endings automatically
• Stdin support — read from stdin by passing fd 0
• Bun compatible — works with Bun runtime
• Deno compatible — works with Deno runtime

Installation

npm install n-readlines

Requirements: Node.js >= 18.x, Bun, or Deno

Quick Start

const LineByLine = require('n-readlines');
const liner = new LineByLine('./textfile.txt');

let line;
while (line = liner.next()) {
    console.log(line.toString());
}

TypeScript

import LineByLine = require('n-readlines');
const liner = new LineByLine('./textfile.txt');

let line: Buffer | null;
while (line = liner.next()) {
    console.log(line.toString());
}

API Reference

Constructor

new LineByLine(filename, [options])
new LineByLine(fd, [options])

Parameter	Type	Description
filename	string	Path to the file to read
fd	number	File descriptor (0 for stdin, or from fs.openSync)
options.readChunk	number	Bytes to read at once. Default: 1024

Methods

.next() → Buffer | null

Returns the next line as a Buffer (without the newline character), or null when end of file is reached.

const line = liner.next();
if (line !== null) {
    console.log(line.toString()); // Convert Buffer to string
}

.reset()

Resets the reader to the beginning of the file.

liner.next(); // Read first line
liner.next(); // Read second line
liner.reset(); // Go back to start
liner.next(); // First line again

Note: reset() does not work with stdin.

.close()

Manually closes the file. Subsequent next() calls will return null.

liner.next();
liner.close(); // Done reading early
liner.next(); // Returns null

Note: When reading from stdin, close() does not close the stdin stream.

.isLast() → boolean

Returns true if the last line has been read and there are no more lines available.

const liner = new LineByLine('./file.txt');

while (true) {
    const line = liner.next();
    if (line === null) break;
    
    console.log(line.toString());
    
    if (liner.isLast()) {
        console.log('This was the last line!');
    }
}

Examples

Basic line reading

const LineByLine = require('n-readlines');
const liner = new LineByLine('./data.txt');

let line;
let lineNumber = 1;

while (line = liner.next()) {
    console.log(`Line ${lineNumber}: ${line.toString('utf8')}`);
    lineNumber++;
}

console.log('Finished reading file');

Reading from stdin

const LineByLine = require('n-readlines');
const liner = new LineByLine(0); // fd 0 = stdin

let line;
while (line = liner.next()) {
    console.log(line.toString());
}

Usage:

echo -e "line1\nline2\nline3" | node script.js
cat file.txt | node script.js

Reading with custom chunk size

const liner = new LineByLine('./large-file.txt', {
    readChunk: 4096 // Read 4KB at a time
});

Processing JSON lines (JSONL/NDJSON)

const LineByLine = require('n-readlines');
const liner = new LineByLine('./data.jsonl');

let line;
while (line = liner.next()) {
    const record = JSON.parse(line.toString());
    console.log(record);
}

Early termination

const liner = new LineByLine('./log.txt');

let line;
while (line = liner.next()) {
    const text = line.toString();
    
    if (text.includes('ERROR')) {
        console.log('Found error:', text);
        liner.close(); // Stop reading
        break;
    }
}

Notes

• Lines are returned as Buffer objects — call .toString() to convert to string
• The newline character is not included in the returned line
• Files without a trailing newline are handled correctly
• Empty lines are preserved and returned as empty buffers
• Returns null (not false) when end of file is reached

Line Ending Support

The library automatically handles all common line ending formats:

Format	Characters	Platform
LF	\n	Unix, Linux, macOS
CRLF	\r\n	Windows
CR	\r	Classic Mac OS

Files with mixed line endings are also supported — each line is detected individually.

License

MIT Yoan Arnaudov