readline-pager 0.2.5 → 0.2.7

package/README.md

@@ -38,6 +38,7 @@ npm install readline-pager
 
 ```ts
 import { createPager } from "readline-pager";
+// const { createPager } = require("readline-pager");
 
 const pager = createPager("./bigfile.txt");
 
@@ -51,8 +52,6 @@ for await (const page of pager) {
 **Recommended for highest throughput:**
 
 ```ts
-const pager = createPager("./bigfile.txt");
-
 while (true) {
   const page = await pager.next();
   if (!page) break;
@@ -60,9 +59,7 @@ while (true) {
 
 // or
 let page;
-while ((page = await pager.next()) !== null) {
-  // process page
-}
+while ((page = await pager.next()) !== null) {}
 ```
 
 - `while + next()` is the fastest iteration method (avoids extra async-iterator overhead).
@@ -76,14 +73,14 @@ while ((page = await pager.next()) !== null) {
 createPager(filepath, {
   chunkSize?: number,     // default: 64 * 1024 (64 KiB)
   pageSize?: number,      // default: 1_000
-  delimiter?: string,      // default: "\n"
+  delimiter?: string,     // default: "\n"
   prefetch?: number,      // default: 1
   backward?: boolean,     // default: false
   useWorker?: boolean,    // default: false (forward only)
 });
 ```
 
-- `chunkSize`: number of bytes read per I/O operation. **Tune this** — default is `64 * 1024`.
+- `chunkSize` — number of bytes read per I/O operation.
 - `pageSize` — number of lines per page.
 - `delimiter` — line separator.
 - `prefetch` — max number of pages buffered internally. Not required for typical use; tuning has little effect once the engine is optimized.
@@ -103,7 +100,7 @@ Returns the next page or `null` when finished. Empty lines are preserved.
 - 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` may emit fewer or no `line` events in these cases.
 
-### `pager.close(): void`
+### `pager.close(): Promise<void>`
 
 Stops reading and releases resources immediately. Safe to call at any time.
 
@@ -121,28 +118,46 @@ Run the included benchmark:
 
 ```bash
 # default run
-node test/_benchmark.ts
+npm run benchmark
 
 # or customize with args
 node test/_benchmark.ts --lines=20000 --page-size=500 --backward
 ```
 
 > Test setup: generated text files with uuid, run on a fast NVMe machine with default options; values are averages from multiple runs. Results are machine-dependent.
+>
+> The **Average Throughput (MB/s)** is computed for two strategies: reading files line by line and page by page.
+>
+> In addition to _Node_, the two other popular JavaScript runtimes were also tested with `readline-pager`.
+
+### Line by line
+
+| Runtime / Method | 1M lines (35 MB) | 10M lines (353 MB) | 100M lines (3,529 MB) | 1,000M lines (35,286 MB) |
+| ---------------- | ---------------: | -----------------: | --------------------: | -----------------------: |
+| Node — node:line |              369 |                435 |                   455 |                      455 |
+| Deno — node:line |              203 |                230 |                   230 |                      229 |
+| Deno — deno:line |              738 |                901 |                   915 |                      809 |
+| Bun — node:line  |              246 |                279 |                   283 |                      280 |
+| Bun — bun:line   |              938 |              1,540 |                 1,668 |                    1,315 |
+
+### Page by page
 
-|  Lines |  File MB | Node `readline` (MB/s) | Bun streaming (MB/s) | `readline-pager` (Node) (MB/s) |
-| -----: | -------: | ---------------------: | -------------------: | -----------------------------: |
-|    10M |   352.86 |                   ~423 |                 ~296 |                     **~1,327** |
-|   100M |  3528.59 |                   ~441 |                 ~298 |                     **~1,378** |
-| 1,000M | 35285.95 |                   ~426 |                 ~294 |                     **~1,168** |
+| Runtime / Method      | 1M lines (35 MB) | 10M lines (353 MB) | 100M lines (3,529 MB) | 1,000M lines (35,286 MB) |
+| --------------------- | ---------------: | -----------------: | --------------------: | -----------------------: |
+| Node — readline-pager |            1,053 |              1,311 |                 1,278 |                      936 |
+| Deno — deno:page      |              852 |                909 |                   908 |                      783 |
+| Deno — readline-pager |            1,131 |              1,268 |                 1,271 |                      911 |
+| Bun — bun:page        |              411 |                440 |                   449 |                      428 |
+| Bun — readline-pager  |              827 |              1,021 |                 1,040 |                      804 |
 
-**Takeaway:** `readline-pager` delivers multi-GB/s memory-to-memory throughput on large files on typical NVMe hardware; results vary with `chunkSize`, runtime (Node vs Bun), and CPU/OS.
+**Runtime Environment:** Node.js v25.6.1 & Bun v1.3.9 & Deno 2.6.10
 
 ---
 
 ## 🛠 Development & Contributing
 
-- Minimum supported Node.js: **v18.12** (lts/hydrogen).
-- Development/test environment: **Node v25.6**, **TypeScript v5.9**.
+- Minimum supported Node.js: **v18.12 (lts/hydrogen)**.
+- Development/test environment: **Node v25.6 & TypeScript v5.9**.
 
 Run tests:
 

package/dist/main.cjs

@@ -1,4 +1,4 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
 let node_fs_promises = require("node:fs/promises");
 let node_worker_threads = require("node:worker_threads");
 
@@ -98,7 +98,10 @@ function createBackwardReader(filepath, options) {
 		closed = true;
 		done = true;
 		pageQueue.queue.length = 0;
-		if (fd) await fd.close();
+		if (fd) {
+			await fd.close();
+			fd = null;
+		}
 	}
 	return {
 		next,
@@ -113,10 +116,14 @@ function createBackwardReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close().catch(() => {});
 			}
 		}
 	};
@@ -187,7 +194,10 @@ function createForwardReader(filepath, options) {
 		closed = true;
 		done = true;
 		pageQueue.queue.length = 0;
-		if (fd) await fd.close();
+		if (fd) {
+			await fd.close();
+			fd = null;
+		}
 	}
 	return {
 		next,
@@ -202,10 +212,14 @@ function createForwardReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close();
 			}
 		}
 	};
@@ -247,7 +261,7 @@ function createWorkerReader(filepath, options) {
 	async function close() {
 		closed = true;
 		done = true;
-		worker.terminate();
+		await worker.terminate();
 	}
 	return {
 		next,
@@ -262,10 +276,14 @@ function createWorkerReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close();
 			}
 		}
 	};
@@ -298,4 +316,5 @@ function createPager(filepath, options = {}) {
 }
 
 //#endregion
-exports.createPager = createPager;
+exports.createPager = createPager;
+exports.default = createPager;

package/dist/main.d.cts

@@ -11,7 +11,7 @@ interface PagerOptions extends Partial<ReaderOptions> {
 }
 interface Pager extends AsyncIterable<string[]> {
   next(): Promise<string[] | null>;
-  close(): void;
+  close(): Promise<void>;
   readonly lineCount: number;
   readonly firstLine: string | null;
   readonly lastLine: string | null;
@@ -20,4 +20,4 @@ interface Pager extends AsyncIterable<string[]> {
 //#region src/main.d.ts
 declare function createPager(filepath: string, options?: PagerOptions): Pager;
 //#endregion
-export { Pager, PagerOptions, ReaderOptions, createPager };
+export { Pager, PagerOptions, ReaderOptions, createPager, createPager as default };

package/dist/main.d.mts

@@ -11,7 +11,7 @@ interface PagerOptions extends Partial<ReaderOptions> {
 }
 interface Pager extends AsyncIterable<string[]> {
   next(): Promise<string[] | null>;
-  close(): void;
+  close(): Promise<void>;
   readonly lineCount: number;
   readonly firstLine: string | null;
   readonly lastLine: string | null;
@@ -20,4 +20,4 @@ interface Pager extends AsyncIterable<string[]> {
 //#region src/main.d.ts
 declare function createPager(filepath: string, options?: PagerOptions): Pager;
 //#endregion
-export { Pager, PagerOptions, ReaderOptions, createPager };
+export { Pager, PagerOptions, ReaderOptions, createPager, createPager as default };

package/dist/main.mjs

@@ -102,7 +102,10 @@ function createBackwardReader(filepath, options) {
 		closed = true;
 		done = true;
 		pageQueue.queue.length = 0;
-		if (fd) await fd.close();
+		if (fd) {
+			await fd.close();
+			fd = null;
+		}
 	}
 	return {
 		next,
@@ -117,10 +120,14 @@ function createBackwardReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close().catch(() => {});
 			}
 		}
 	};
@@ -191,7 +198,10 @@ function createForwardReader(filepath, options) {
 		closed = true;
 		done = true;
 		pageQueue.queue.length = 0;
-		if (fd) await fd.close();
+		if (fd) {
+			await fd.close();
+			fd = null;
+		}
 	}
 	return {
 		next,
@@ -206,10 +216,14 @@ function createForwardReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close();
 			}
 		}
 	};
@@ -251,7 +265,7 @@ function createWorkerReader(filepath, options) {
 	async function close() {
 		closed = true;
 		done = true;
-		worker.terminate();
+		await worker.terminate();
 	}
 	return {
 		next,
@@ -266,10 +280,14 @@ function createWorkerReader(filepath, options) {
 			return lastLine;
 		},
 		async *[Symbol.asyncIterator]() {
-			while (true) {
-				const p = await next();
-				if (!p) break;
-				yield p;
+			try {
+				while (true) {
+					const p = await next();
+					if (!p) break;
+					yield p;
+				}
+			} finally {
+				await close();
 			}
 		}
 	};
@@ -302,4 +320,4 @@ function createPager(filepath, options = {}) {
 }
 
 //#endregion
-export { createPager };
+export { createPager, createPager as default };

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "readline-pager",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "scripts": {
     "build": "tsdown",
     "pretest": "npm run build",
     "test": "node --test --experimental-test-coverage test/**/*.test.ts",
-    "prepublishOnly": "npm run build && npm run test"
+    "prepublishOnly": "npm run build && npm run test",
+    "benchmark": "node test/_benchmark.ts; bun test/_benchmark.ts; deno --allow-write --allow-read test/_benchmark.ts"
   },
   "devDependencies": {
     "@types/bun": "~1.3.9",
+    "@types/deno": "~2.5.0",
     "@types/node": "~25.3.0",
     "prettier": "~3.8.1",
     "prettier-plugin-organize-imports": "~4.3.0",