readline-pager 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# readline-pager
+
+Memory-efficient, paginated file reader for Node.js with async iteration, prefetching, backward reading and optional worker support.
+
+`readline-pager` reads large text files page-by-page without loading the entire file into memory.
+
+- ✅ Zero dependencies
+- ✅ Async iterator support (`for await...of`)
+- ✅ Forward & backward reading (read from EOF → BOF)
+- ✅ Optional worker thread mode (forward only)
+- ✅ Up to ~3× faster than vanilla Node.js `readline`
+- ✅ ~97% test coverage & Fully typed (TypeScript)
+
+---
+
+## Installation
+
+```bash
+npm install readline-pager
+```
+
+---
+
+## Quick Start
+
+```ts
+import { createPager } from "readline-pager";
+
+const pager = createPager("./bigfile.txt");
+
+for await (const page of pager) {
+  console.log(page[0]); // first line of the current page
+}
+```
+
+---
+
+## Manual iteration (recommended for max throughput)
+
+```ts
+const pager = createPager("./bigfile.txt");
+
+let page;
+while ((page = await pager.next()) !== null) {
+  // page: string[]
+  // process page
+}
+```
+
+`pager.next()` returns:
+
+- `Promise<string[]>` — next page
+- `Promise<null>` — end of file
+
+> Use `while + next()` when raw throughput matters (see Iteration Performance Notes).
+
+---
+
+## Options
+
+```ts
+createPager(filepath, {
+  pageSize?: number,      // default: 1_000
+  delimiter?: string      // default: "\n"
+  prefetch?: number,      // default: 1
+  backward?: boolean,     // default: false
+  useWorker?: boolean,    // default: false (forward only)
+});
+```
+
+- `pageSize` — number of lines per page.
+- `delimiter` — line separator.
+- `prefetch` — max pages buffered internally. Higher increases throughput but uses more memory.
+- `backward` — read file from end → start (not supported with `useWorker`).
+- `useWorker` — move parsing to a worker thread (forward only).
+
+---
+
+## API
+
+### `pager.next(): Promise<string[] | null>`
+
+Returns the next page or `null` when finished. Empty lines are preserved.
+
+**Note:** Unlike Node.js `readline`, which skips empty files or empty lines at the start, `readline-pager` always returns all lines.
+
+- A completely empty file (`0` bytes) produces `[""]` on the first read.
+- A file with multiple empty lines returns each line as an empty string (e.g., `["", ""]` for two empty lines). Node.js `readline` would emit fewer or no `line` events in these cases.
+
+✅ Key points:
+
+- A 0-byte file → `[""]`
+- Consecutive `\n\n` → `["", ""]`
+- Node.js `readline` skips first empty line(s) and might emit nothing for empty files.
+
+### `pager.close(): void`
+
+Stops reading and releases resources immediately. Safe to call any time.
+
+### Properties
+
+```ts
+pager.lineCount; // total lines emitted so far
+pager.firstLine; // first line emitted (available after first read)
+pager.lastLine; // last line emitted (updated each page)
+```
+
+---
+
+## Benchmark
+
+Run the included benchmark:
+
+```bash
+# default run
+node test/benchmark.ts
+
+# or customize
+node test/benchmark.ts --lines=20000 --page-size=500 --prefetch=4 --backward
+```
+
+Benchmarks were executed on a high-end consumer Linux machine (SSD + fast CPU) using generated files.
+
+### Summary (averages)
+
+| Lines       | File Size (MB) | Implementation | Avg Time (ms) | Avg Throughput (MB/s) | Speedup vs `readline` |
+| ----------- | -------------- | -------------- | ------------- | --------------------: | --------------------: |
+| 1,000,000   | 35.29 MB       | readline       | 100.21        |                352.31 |                     — |
+| 1,000,000   | 35.29 MB       | readline-pager | 43.31         |                815.71 |      **2.32× faster** |
+| 10,000,000  | 352.86 MB      | readline       | 802.61        |                439.80 |                     — |
+| 10,000,000  | 352.86 MB      | readline-pager | 292.33        |               1207.77 |      **2.75× faster** |
+| 100,000,000 | 3528.59 MB     | readline       | 7777.52       |                453.75 |                     — |
+| 100,000,000 | 3528.59 MB     | readline-pager | 2742.99       |               1286.50 |      **2.83× faster** |
+
+**Key takeaways**
+
+- `readline-pager` is consistently **~2.3×–2.8× faster** than Node.js `readline`.
+- Relative gain increases with file size.
+- Sustained throughput exceeds **1.2 GB/s** on large files (machine-dependent).
+
+---
+
+## Iteration performance notes
+
+- **Fastest**: manual `while ((page = await pager.next()) !== null) { ... }`
+  Avoids async-iterator protocol overhead and microtask churn.
+
+- **More ergonomic**: `for await (const page of pager) { ... }`
+  Cleaner but slightly slower in hot paths.
+
+**Recommendation:** use the explicit `next()` loop for benchmarks and performance-critical code; use `for await...of` for clarity in less performance-sensitive code.
+
+---
+
+## Development & Contributing
+
+- Minimum supported Node.js: **18.12+** (LTS).
+- Development/test environment used by the author: **Node v25.6.1**, TypeScript `~5.9.x`.
+- To run tests & coverage:
+
+```bash
+npm ci
+npm test
+```
+
+If you want to contribute, open an issue or PR. A `CONTRIBUTING.md` is welcome for larger workflow notes.
+
+---
+
+## License
+
+MIT — © Morteza Jamshidi

package/dist/constants-BNKQoOqH.mjs

@@ -0,0 +1,6 @@
+//#region src/constants.ts
+const CHUNK_SIZE = 64 * 1024;
+const ENCODING = "utf8";
+
+//#endregion
+export { ENCODING as n, CHUNK_SIZE as t };

package/dist/constants-Cyb_UQAC.cjs

@@ -0,0 +1,18 @@
+
+//#region src/constants.ts
+const CHUNK_SIZE = 64 * 1024;
+const ENCODING = "utf8";
+
+//#endregion
+Object.defineProperty(exports, 'CHUNK_SIZE', {
+  enumerable: true,
+  get: function () {
+    return CHUNK_SIZE;
+  }
+});
+Object.defineProperty(exports, 'ENCODING', {
+  enumerable: true,
+  get: function () {
+    return ENCODING;
+  }
+});

package/dist/main.cjs

@@ -0,0 +1,298 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_constants = require('./constants-Cyb_UQAC.cjs');
+let node_fs_promises = require("node:fs/promises");
+let node_worker_threads = require("node:worker_threads");
+
+//#region src/queue.ts
+function createPageQueue() {
+	const queue = [];
+	let resolver = null;
+	return {
+		queue,
+		push(page) {
+			queue.push(page);
+			resolver?.();
+			resolver = null;
+		},
+		wake() {
+			resolver?.();
+			resolver = null;
+		},
+		async shift(done) {
+			if (queue.length) return queue.shift();
+			if (done()) return null;
+			await new Promise((r) => resolver = r);
+			if (queue.length) return queue.shift();
+			if (done()) return null;
+			return null;
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/backward.reader.ts
+function createBackwardReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const pageQueue = createPageQueue();
+	let fd = null;
+	let pos = 0;
+	let buffer = "";
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	const local = [];
+	async function init() {
+		if (fd) return;
+		fd = await (0, node_fs_promises.open)(filepath, "r");
+		pos = (await fd.stat()).size;
+		if (pos === 0) done = true;
+	}
+	async function fill() {
+		if (done || closed) return;
+		await init();
+		if (!fd) return;
+		while (pageQueue.queue.length < prefetch && pos > 0) {
+			const readSize = Math.min(require_constants.CHUNK_SIZE, pos);
+			pos -= readSize;
+			const buf = Buffer.allocUnsafe(readSize);
+			await fd.read(buf, 0, readSize, pos);
+			buffer += buf.toString(require_constants.ENCODING);
+			let idx;
+			while ((idx = buffer.lastIndexOf(delimiter)) !== -1) {
+				const line = buffer.slice(idx + delimiter.length);
+				buffer = buffer.slice(0, idx);
+				local.push(line);
+				while (local.length >= pageSize) {
+					const page = local.splice(0, pageSize);
+					pageQueue.push(page);
+				}
+			}
+		}
+		if (pos === 0) {
+			local.push(buffer);
+			buffer = "";
+			while (local.length > 0) {
+				const sliceSize = Math.min(pageSize, local.length);
+				const page = local.splice(local.length - sliceSize, sliceSize);
+				pageQueue.push(page);
+			}
+			done = true;
+			if (fd) {
+				await fd.close();
+				fd = null;
+			}
+		}
+	}
+	async function next() {
+		if (closed) return null;
+		await fill();
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		pageQueue.queue.length = 0;
+		if (fd) await fd.close();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/forward.reader.ts
+function createForwardReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const pageQueue = createPageQueue();
+	let fd = null;
+	let pos = 0;
+	let size = 0;
+	let buffer = "";
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	const local = [];
+	async function init() {
+		if (fd) return;
+		fd = await (0, node_fs_promises.open)(filepath, "r");
+		size = (await fd.stat()).size;
+		if (size === 0) done = true;
+	}
+	async function fill() {
+		if (done || closed) return;
+		await init();
+		if (!fd) return;
+		while (pageQueue.queue.length < prefetch && pos < size) {
+			const readSize = Math.min(require_constants.CHUNK_SIZE, size - pos);
+			const buf = Buffer.allocUnsafe(readSize);
+			const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+			pos += bytesRead;
+			buffer += buf.toString(require_constants.ENCODING, 0, bytesRead);
+			let idx;
+			while ((idx = buffer.indexOf(delimiter)) !== -1) {
+				const line = buffer.slice(0, idx);
+				buffer = buffer.slice(idx + delimiter.length);
+				local.push(line);
+				while (local.length >= pageSize) pageQueue.push(local.splice(0, pageSize));
+			}
+		}
+		if (pos >= size) {
+			const parts = buffer.length > 0 ? buffer.split(delimiter) : [""];
+			for (const line of parts) local.push(line);
+			buffer = "";
+			while (local.length > 0) pageQueue.push(local.splice(0, pageSize));
+			done = true;
+			if (fd) {
+				await fd.close();
+				fd = null;
+			}
+		}
+	}
+	async function next() {
+		if (closed) return null;
+		await fill();
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		pageQueue.queue.length = 0;
+		if (fd) await fd.close();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/worker.reader.ts
+const workerFile = typeof {} !== "undefined" ? new URL("./worker.mjs", require("url").pathToFileURL(__filename).href) : require.resolve("./worker.cjs");
+function createWorkerReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const worker = new node_worker_threads.Worker(new URL(workerFile, require("url").pathToFileURL(__filename).href), { workerData: {
+		filepath,
+		pageSize,
+		delimiter
+	} });
+	const pageQueue = createPageQueue();
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	worker.on("message", (msg) => {
+		if (msg.type === "page") pageQueue.push(msg.data);
+		if (msg.type === "done") {
+			done = true;
+			pageQueue.wake();
+		}
+	});
+	async function next() {
+		if (closed) return null;
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		worker.terminate();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/main.ts
+function createPager(filepath, options = {}) {
+	const { pageSize = 1e3, delimiter = "\n", prefetch = 1, backward = false, useWorker = false } = options;
+	if (!filepath) throw new Error("filepath required");
+	if (pageSize <= 0) throw new RangeError("pageSize must be > 0");
+	if (prefetch <= 0) throw new RangeError("prefetch must be >= 1");
+	if (backward && useWorker) throw new Error("backward not supported with useWorker");
+	return useWorker ? createWorkerReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	}) : backward ? createBackwardReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	}) : createForwardReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	});
+}
+
+//#endregion
+exports.createPager = createPager;

package/dist/main.d.cts

@@ -0,0 +1,22 @@
+//#region src/types.d.ts
+interface ReaderOptions {
+  pageSize: number;
+  delimiter: string;
+  prefetch: number;
+}
+interface PagerOptions extends Partial<ReaderOptions> {
+  backward?: boolean;
+  useWorker?: boolean;
+}
+interface Pager extends AsyncIterable<string[]> {
+  next(): Promise<string[] | null>;
+  close(): void;
+  readonly lineCount: number;
+  readonly firstLine: string | null;
+  readonly lastLine: string | null;
+}
+//#endregion
+//#region src/main.d.ts
+declare function createPager(filepath: string, options?: PagerOptions): Pager;
+//#endregion
+export { Pager, PagerOptions, ReaderOptions, createPager };

package/dist/main.d.mts

@@ -0,0 +1,22 @@
+//#region src/types.d.ts
+interface ReaderOptions {
+  pageSize: number;
+  delimiter: string;
+  prefetch: number;
+}
+interface PagerOptions extends Partial<ReaderOptions> {
+  backward?: boolean;
+  useWorker?: boolean;
+}
+interface Pager extends AsyncIterable<string[]> {
+  next(): Promise<string[] | null>;
+  close(): void;
+  readonly lineCount: number;
+  readonly firstLine: string | null;
+  readonly lastLine: string | null;
+}
+//#endregion
+//#region src/main.d.ts
+declare function createPager(filepath: string, options?: PagerOptions): Pager;
+//#endregion
+export { Pager, PagerOptions, ReaderOptions, createPager };

package/dist/main.mjs

@@ -0,0 +1,302 @@
+import { n as ENCODING, t as CHUNK_SIZE } from "./constants-BNKQoOqH.mjs";
+import { createRequire } from "node:module";
+import { open } from "node:fs/promises";
+import { Worker } from "node:worker_threads";
+
+//#region \0rolldown/runtime.js
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+//#region src/queue.ts
+function createPageQueue() {
+	const queue = [];
+	let resolver = null;
+	return {
+		queue,
+		push(page) {
+			queue.push(page);
+			resolver?.();
+			resolver = null;
+		},
+		wake() {
+			resolver?.();
+			resolver = null;
+		},
+		async shift(done) {
+			if (queue.length) return queue.shift();
+			if (done()) return null;
+			await new Promise((r) => resolver = r);
+			if (queue.length) return queue.shift();
+			if (done()) return null;
+			return null;
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/backward.reader.ts
+function createBackwardReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const pageQueue = createPageQueue();
+	let fd = null;
+	let pos = 0;
+	let buffer = "";
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	const local = [];
+	async function init() {
+		if (fd) return;
+		fd = await open(filepath, "r");
+		pos = (await fd.stat()).size;
+		if (pos === 0) done = true;
+	}
+	async function fill() {
+		if (done || closed) return;
+		await init();
+		if (!fd) return;
+		while (pageQueue.queue.length < prefetch && pos > 0) {
+			const readSize = Math.min(CHUNK_SIZE, pos);
+			pos -= readSize;
+			const buf = Buffer.allocUnsafe(readSize);
+			await fd.read(buf, 0, readSize, pos);
+			buffer += buf.toString(ENCODING);
+			let idx;
+			while ((idx = buffer.lastIndexOf(delimiter)) !== -1) {
+				const line = buffer.slice(idx + delimiter.length);
+				buffer = buffer.slice(0, idx);
+				local.push(line);
+				while (local.length >= pageSize) {
+					const page = local.splice(0, pageSize);
+					pageQueue.push(page);
+				}
+			}
+		}
+		if (pos === 0) {
+			local.push(buffer);
+			buffer = "";
+			while (local.length > 0) {
+				const sliceSize = Math.min(pageSize, local.length);
+				const page = local.splice(local.length - sliceSize, sliceSize);
+				pageQueue.push(page);
+			}
+			done = true;
+			if (fd) {
+				await fd.close();
+				fd = null;
+			}
+		}
+	}
+	async function next() {
+		if (closed) return null;
+		await fill();
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		pageQueue.queue.length = 0;
+		if (fd) await fd.close();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/forward.reader.ts
+function createForwardReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const pageQueue = createPageQueue();
+	let fd = null;
+	let pos = 0;
+	let size = 0;
+	let buffer = "";
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	const local = [];
+	async function init() {
+		if (fd) return;
+		fd = await open(filepath, "r");
+		size = (await fd.stat()).size;
+		if (size === 0) done = true;
+	}
+	async function fill() {
+		if (done || closed) return;
+		await init();
+		if (!fd) return;
+		while (pageQueue.queue.length < prefetch && pos < size) {
+			const readSize = Math.min(CHUNK_SIZE, size - pos);
+			const buf = Buffer.allocUnsafe(readSize);
+			const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+			pos += bytesRead;
+			buffer += buf.toString(ENCODING, 0, bytesRead);
+			let idx;
+			while ((idx = buffer.indexOf(delimiter)) !== -1) {
+				const line = buffer.slice(0, idx);
+				buffer = buffer.slice(idx + delimiter.length);
+				local.push(line);
+				while (local.length >= pageSize) pageQueue.push(local.splice(0, pageSize));
+			}
+		}
+		if (pos >= size) {
+			const parts = buffer.length > 0 ? buffer.split(delimiter) : [""];
+			for (const line of parts) local.push(line);
+			buffer = "";
+			while (local.length > 0) pageQueue.push(local.splice(0, pageSize));
+			done = true;
+			if (fd) {
+				await fd.close();
+				fd = null;
+			}
+		}
+	}
+	async function next() {
+		if (closed) return null;
+		await fill();
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		pageQueue.queue.length = 0;
+		if (fd) await fd.close();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/reader/worker.reader.ts
+const workerFile = typeof import.meta !== "undefined" ? new URL("./worker.mjs", import.meta.url) : __require.resolve("./worker.cjs");
+function createWorkerReader(filepath, options) {
+	const { pageSize, delimiter, prefetch } = options;
+	const worker = new Worker(new URL(workerFile, import.meta.url), { workerData: {
+		filepath,
+		pageSize,
+		delimiter
+	} });
+	const pageQueue = createPageQueue();
+	let done = false;
+	let closed = false;
+	let emittedCount = 0;
+	let firstLine = null;
+	let lastLine = null;
+	worker.on("message", (msg) => {
+		if (msg.type === "page") pageQueue.push(msg.data);
+		if (msg.type === "done") {
+			done = true;
+			pageQueue.wake();
+		}
+	});
+	async function next() {
+		if (closed) return null;
+		const page = await pageQueue.shift(() => done);
+		if (!page) return null;
+		emittedCount += page.length;
+		firstLine ??= page[0];
+		lastLine = page[page.length - 1];
+		return page;
+	}
+	async function close() {
+		closed = true;
+		done = true;
+		worker.terminate();
+	}
+	return {
+		next,
+		close,
+		get lineCount() {
+			return emittedCount;
+		},
+		get firstLine() {
+			return firstLine;
+		},
+		get lastLine() {
+			return lastLine;
+		},
+		async *[Symbol.asyncIterator]() {
+			while (true) {
+				const p = await next();
+				if (!p) break;
+				yield p;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/main.ts
+function createPager(filepath, options = {}) {
+	const { pageSize = 1e3, delimiter = "\n", prefetch = 1, backward = false, useWorker = false } = options;
+	if (!filepath) throw new Error("filepath required");
+	if (pageSize <= 0) throw new RangeError("pageSize must be > 0");
+	if (prefetch <= 0) throw new RangeError("prefetch must be >= 1");
+	if (backward && useWorker) throw new Error("backward not supported with useWorker");
+	return useWorker ? createWorkerReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	}) : backward ? createBackwardReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	}) : createForwardReader(filepath, {
+		pageSize,
+		prefetch,
+		delimiter
+	});
+}
+
+//#endregion
+export { createPager };

package/dist/worker.cjs

@@ -0,0 +1,38 @@
+const require_constants = require('./constants-Cyb_UQAC.cjs');
+let node_fs_promises = require("node:fs/promises");
+let node_worker_threads = require("node:worker_threads");
+
+//#region src/worker.ts
+const { filepath, pageSize, delimiter } = node_worker_threads.workerData;
+(async () => {
+	const fd = await (0, node_fs_promises.open)(filepath, "r");
+	const { size } = await fd.stat();
+	let pos = 0;
+	let buffer = "";
+	const local = [];
+	while (pos < size) {
+		const readSize = Math.min(require_constants.CHUNK_SIZE, size - pos);
+		const buf = Buffer.allocUnsafe(readSize);
+		const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+		pos += bytesRead;
+		buffer += buf.toString("utf8", 0, bytesRead);
+		const parts = buffer.split(delimiter);
+		buffer = parts.pop() ?? "";
+		for (const line of parts) {
+			local.push(line);
+			if (local.length === pageSize) node_worker_threads.parentPort?.postMessage({
+				type: "page",
+				data: local.splice(0)
+			});
+		}
+	}
+	if (buffer !== "") local.push(buffer);
+	if (local.length) node_worker_threads.parentPort?.postMessage({
+		type: "page",
+		data: local
+	});
+	node_worker_threads.parentPort?.postMessage({ type: "done" });
+	await fd.close();
+})();
+
+//#endregion

package/dist/worker.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/worker.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/worker.mjs

@@ -0,0 +1,39 @@
+import { t as CHUNK_SIZE } from "./constants-BNKQoOqH.mjs";
+import { open } from "node:fs/promises";
+import { parentPort, workerData } from "node:worker_threads";
+
+//#region src/worker.ts
+const { filepath, pageSize, delimiter } = workerData;
+(async () => {
+	const fd = await open(filepath, "r");
+	const { size } = await fd.stat();
+	let pos = 0;
+	let buffer = "";
+	const local = [];
+	while (pos < size) {
+		const readSize = Math.min(CHUNK_SIZE, size - pos);
+		const buf = Buffer.allocUnsafe(readSize);
+		const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+		pos += bytesRead;
+		buffer += buf.toString("utf8", 0, bytesRead);
+		const parts = buffer.split(delimiter);
+		buffer = parts.pop() ?? "";
+		for (const line of parts) {
+			local.push(line);
+			if (local.length === pageSize) parentPort?.postMessage({
+				type: "page",
+				data: local.splice(0)
+			});
+		}
+	}
+	if (buffer !== "") local.push(buffer);
+	if (local.length) parentPort?.postMessage({
+		type: "page",
+		data: local
+	});
+	parentPort?.postMessage({ type: "done" });
+	await fd.close();
+})();
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "readline-pager",
+  "version": "0.2.1",
+  "scripts": {
+    "build": "tsdown",
+    "pretest": "npm run build",
+    "test": "node --test --experimental-test-coverage test/**/*.test.ts",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "devDependencies": {
+    "@types/node": "~25.3.0",
+    "prettier": "~3.8.1",
+    "prettier-plugin-organize-imports": "~4.3.0",
+    "tsdown": "~0.20.3",
+    "typescript": "~5.9.3"
+  },
+  "type": "module",
+  "main": "./dist/main.cjs",
+  "module": "./dist/main.mjs",
+  "types": "./dist/main.d.mts",
+  "exports": {
+    ".": {
+      "require": "./dist/main.cjs",
+      "import": "./dist/main.mjs",
+      "types": "./dist/main.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nodejs",
+    "readline",
+    "readline-pager",
+    "pager",
+    "file-reader",
+    "pagination",
+    "large-files",
+    "async-iterator",
+    "streaming",
+    "memory-efficient",
+    "high-performance",
+    "log-processing",
+    "backward-reading"
+  ],
+  "description": "Memory-efficient, paginated file reader for Node.js with async iteration, prefetching, backward reading and optional worker support.",
+  "engines": {
+    "node": ">=18.12"
+  },
+  "author": "Morteza Jamshidi",
+  "license": "MIT"
+}