readline-pager 0.2.6 → 0.3.0

package/README.md

@@ -12,17 +12,18 @@
   <img src="https://img.shields.io/github/stars/devmor-j/readline-pager" alt="stars">
 </p>
 
-⚡ 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.
+⚡ Memory-efficient paginated file reader for Node.js with async and sync 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 (`for await...of`) + manual `next()` API
+- ✅ Sync iterator (`for...of`) + manual `nextSync()` API
 - ✅ Forward & backward reading (EOF → BOF)
 - ✅ Optional worker thread mode (forward only)
-- ✅ Up to ~3x faster than Node.js `readline`
+- ✅ Up to ~3× faster than Node.js `readline`
 - ✅ ~97% test coverage & fully typed (TypeScript)
 
-> **Important:**
-> Performance is heavily dependent on the `chunkSize` option; ensure you fine-tune it for your specific I/O hardware. A setting of **64 KB** is typically a good starting point. Increasing it might gradually improve read speeds, usually reaching an optimal peak depending on your hardware's capabilities.
+> **Important:**  
+> Performance depends heavily on the `chunkSize` option. Tune it for your specific I/O hardware. A value of **64 KB** is usually a good starting point. Increasing it may gradually improve throughput until reaching the optimal point for your hardware.
 
 ---
 
@@ -42,31 +43,28 @@ import { createPager } from "readline-pager";
 
 const pager = createPager("./bigfile.txt");
 
+// Async iteration
 for await (const page of pager) {
   console.log(page[0]); // first line of the current page
 }
-```
-
----
 
-**Recommended for highest throughput:**
+// Sync iteration
+for (const page of pager) {
+}
 
-```ts
+// Manual next
 while (true) {
   const page = await pager.next();
   if (!page) break;
 }
 
-// or
+// Manual nextSync (also with condition variation)
 let page;
-while ((page = await pager.next()) !== null) {}
+while ((page = pager.nextSync()) !== null) {
+  console.log(page[0]);
+}
 ```
 
-- `while + next()` is the fastest iteration method (avoids extra async-iterator overhead).
-- `for await of` is more ergonomic and convenient.
-
----
-
 ## ⚙️ Options
 
 ```ts
@@ -74,18 +72,18 @@ createPager(filepath, {
   chunkSize?: number,     // default: 64 * 1024 (64 KiB)
   pageSize?: number,      // default: 1_000
   delimiter?: string,     // default: "\n"
-  prefetch?: number,      // default: 1
+  prefetch?: number,      // default: 8
   backward?: boolean,     // default: false
-  useWorker?: boolean,    // default: false (forward only)
+  useWorker?: boolean,    // default: false
 });
 ```
 
 - `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.
-- `backward` — read file from end → start (not supported with `useWorker`).
-- `useWorker` — offload parsing to a worker thread (forward only).
+- `prefetch` — maximum number of pages buffered internally.
+- `backward` — read the file from end → start (not supported with `useWorker`).
+- `useWorker` — offload reading to a worker thread (forward reading only).
 
 ---
 
@@ -93,46 +91,73 @@ createPager(filepath, {
 
 ### `pager.next(): Promise<string[] | null>`
 
-Returns the next page or `null` when finished. Empty lines are preserved.
+Returns the next page asynchronously.
 
-**Note:** Unlike Node.js `readline`, which may skip empty files or leading empty lines, `readline-pager` always returns all lines.
+Returns `null` when the end of the file is reached.
 
-- 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.
+Empty lines are preserved.
 
-### `pager.close(): void`
+---
+
+### `pager.nextSync(): string[] | null`
+
+Synchronous version of `pager.next()`.
 
-Stops reading and releases resources immediately. Safe to call at any time.
+Returns the next page immediately or `null` when the end of the file is reached.
+
+---
 
-### Read-only properties
+### `pager.close(): Promise<void>`
 
-- `pager.lineCount` — lines emitted so far
-- `pager.firstLine` — first emitted line (available after first read)
-- `pager.lastLine` — last emitted line (updated per page)
+Stops reading and releases resources asynchronously. Safe to call at any time.
 
 ---
 
+**Note:**
+Unlike Node.js `readline`, which may skip empty files or leading empty lines, `readline-pager` always returns all lines.
+
+- A completely empty file (`0` bytes) produces `[""]` on the first read.
+- A file containing multiple empty lines returns each line as an empty string (for example `["", ""]` for two empty lines).
+
 ## 📊 Benchmark
 
 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.
-
-|  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 Environment:** Node.js v25.6.1 & Bun v1.3.9
+>
+> 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
+
+| 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 |
+
+**Runtime Environment:** Node.js v25.6.1 & Bun v1.3.9 & Deno 2.6.10
 
 ---