readline-pager 0.7.3 → 0.8.0

package/README.md

@@ -76,7 +76,12 @@ while ((page = pager.nextSync()) !== null) {}
 // Native C++
 for (const page of createNativePager("./bigfile.txt")) {
 }
-```
+
+// Automatic cleanup on exit (optional, requires Node.js v22+)
+await using pager = createPager("./bigfile.txt");
+for await (const page of pager) {
+}
+// pager will be disposed automatically when it goes out of scope
 
 ---
 
@@ -148,10 +153,9 @@ Stops reading and releases resources asynchronously. Safe to call at any time.
 Run the benchmark locally:
 
 ```bash
-npm run benchmark:node
-
-# or customize with args
-node test/benchmark.ts --lines=20000 --page-size=500 --backward
+npm run benchmark                   # default: Node.js
+npm run benchmark -- deno           # Deno runtime
+npm run benchmark -- bun --backward # Bun runtime with custom args
 ```
 
 > Test setup: generated text files (UUID lines), NVMe SSD, Node.js runtime.
@@ -170,7 +174,7 @@ node test/benchmark.ts --lines=20000 --page-size=500 --backward
 ## 🛠 Development & Contributing
 
 - Minimum supported Node.js: **v18.12**
-- Development/test environment: **Node v25.8** and **TypeScript v6.0**
+- Development/test environment: **Node v26.3** and **TypeScript v6.0**
 
 Run tests:
 

package/dist/main.cjs

@@ -1,7 +1,4 @@
-Object.defineProperties(exports, {
-	__esModule: { value: true },
-	[Symbol.toStringTag]: { value: "Module" }
-});
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_native = require("./native.cjs");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
@@ -156,30 +153,33 @@ function createBackwardReader(filepath, options) {
 			pageQueue.wake();
 			return;
 		}
-		while (!done && !closed) {
-			while (pageQueue.count < prefetch && pos > 0 && !closed) {
-				const readSize = Math.min(chunkSize, pos);
-				pos -= readSize;
-				const buf = Buffer.allocUnsafe(readSize);
-				const { bytesRead } = await fd.read(buf, 0, readSize, pos);
-				if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
-				else {
-					buffer = buf.toString("utf8", 0, bytesRead) + buffer;
-					if (pos === 0 && buffer.startsWith(delimiter)) startsWithDelimiter = true;
-					consumeBuffer();
+		try {
+			while (!done && !closed) {
+				while (pageQueue.count < prefetch && pos > 0 && !closed) {
+					const readSize = Math.min(chunkSize, pos);
+					pos -= readSize;
+					const buf = Buffer.allocUnsafe(readSize);
+					const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+					if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
+					else {
+						buffer = buf.toString("utf8", 0, bytesRead) + buffer;
+						if (pos === 0 && buffer.startsWith(delimiter)) startsWithDelimiter = true;
+						consumeBuffer();
+					}
 				}
-			}
-			if (pos === 0 && !flushed) {
-				flushTail();
-				if (fd) {
-					try {
-						await fd.close();
-					} catch {}
-					fd = null;
+				if (pos === 0 && !flushed) {
+					flushTail();
+					break;
 				}
-				break;
+				if (!done && !closed) await new Promise((r) => setImmediate(r));
+			}
+		} finally {
+			if (fd) {
+				try {
+					await fd.close();
+				} catch {}
+				fd = null;
 			}
-			if (!done && !closed) await new Promise((r) => setImmediate(r));
 		}
 	})();
 	function fillSync() {
@@ -265,13 +265,29 @@ function createBackwardReader(filepath, options) {
 					} catch {}
 					fdSync = null;
 				}
-				if (fd?.fd) {
-					try {
-						(0, node_fs.closeSync)(fd.fd);
-					} catch {}
+				if (fd) {
+					fd.close().catch(() => {});
 					fd = null;
 				}
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			closed = true;
+			done = true;
+			pageQueue.clear();
+			if (fdSync) {
+				try {
+					(0, node_fs.closeSync)(fdSync);
+				} catch {}
+				fdSync = null;
+			}
+			if (fd) {
+				fd.close().catch(() => {});
+				fd = null;
+			}
 		}
 	};
 }
@@ -337,29 +353,32 @@ function createForwardReader(filepath, options) {
 			pageQueue.wake();
 			return;
 		}
-		while (!done && !closed) {
-			while (pageQueue.count < prefetch && pos < size && !closed) {
-				const readSize = Math.min(chunkSize, size - pos);
-				const buf = Buffer.allocUnsafe(readSize);
-				const { bytesRead } = await fd.read(buf, 0, readSize, pos);
-				pos += bytesRead;
-				if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
-				else {
-					buffer = buffer + buf.toString("utf8", 0, bytesRead);
-					consumeBuffer();
+		try {
+			while (!done && !closed) {
+				while (pageQueue.count < prefetch && pos < size && !closed) {
+					const readSize = Math.min(chunkSize, size - pos);
+					const buf = Buffer.allocUnsafe(readSize);
+					const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+					pos += bytesRead;
+					if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
+					else {
+						buffer = buffer + buf.toString("utf8", 0, bytesRead);
+						consumeBuffer();
+					}
 				}
-			}
-			if (pos >= size && !flushed) {
-				flushTail();
-				if (fd) {
-					try {
-						await fd.close();
-					} catch {}
-					fd = null;
+				if (pos >= size && !flushed) {
+					flushTail();
+					break;
 				}
-				break;
+				if (!done && !closed) await new Promise((r) => setImmediate(r));
+			}
+		} finally {
+			if (fd) {
+				try {
+					await fd.close();
+				} catch {}
+				fd = null;
 			}
-			if (!done && !closed) await new Promise((r) => setImmediate(r));
 		}
 	})();
 	function fillSync() {
@@ -444,13 +463,29 @@ function createForwardReader(filepath, options) {
 					} catch {}
 					fdSync = null;
 				}
-				if (fd?.fd) {
-					try {
-						(0, node_fs.closeSync)(fd.fd);
-					} catch {}
+				if (fd) {
+					fd.close().catch(() => {});
 					fd = null;
 				}
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			closed = true;
+			done = true;
+			pageQueue.clear();
+			if (fdSync) {
+				try {
+					(0, node_fs.closeSync)(fdSync);
+				} catch {}
+				fdSync = null;
+			}
+			if (fd) {
+				fd.close().catch(() => {});
+				fd = null;
+			}
 		}
 	};
 }
@@ -468,14 +503,8 @@ function createPager(filepath, options = {}) {
 		delimiter,
 		output
 	};
-	const reader = backward ? createBackwardReader(filepath, readerOptions) : createForwardReader(filepath, readerOptions);
-	if (process.env.PAGER_TEST_CLEANUPS) {
-		globalThis.__pager_test_cleanups__ ??= [];
-		globalThis.__pager_test_cleanups__.push(reader.close);
-	}
-	return reader;
+	return backward ? createBackwardReader(filepath, readerOptions) : createForwardReader(filepath, readerOptions);
 }
 //#endregion
 exports.createNativePager = require_native.createNativePager;
 exports.createPager = createPager;
-exports.default = createPager;

package/dist/main.d.cts

@@ -1,4 +1,4 @@
-import { i as PagerOptions, n as Output, r as Pager, t as createNativePager } from "./native-7FzZtBp1.cjs";
+import { i as PagerOptions, n as Output, r as Pager, t as createNativePager } from "./native-BJ3yhPgn.cjs";
 
 //#region src/main.d.ts
 declare function createPager<T extends Output>(filepath: string, options: PagerOptions & {
@@ -6,4 +6,4 @@ declare function createPager<T extends Output>(filepath: string, options: PagerO
 }): Pager<T>;
 declare function createPager(filepath: string, options?: PagerOptions): Pager<"string">;
 //#endregion
-export { type Pager, type PagerOptions, createNativePager, createPager, createPager as default };
+export { type Pager, type PagerOptions, createNativePager, createPager };

package/dist/main.d.mts

@@ -1,4 +1,4 @@
-import { i as PagerOptions, n as Output, r as Pager, t as createNativePager } from "./native-B0PXEEYw.mjs";
+import { i as PagerOptions, n as Output, r as Pager, t as createNativePager } from "./native-BJ3yhPgn.mjs";
 
 //#region src/main.d.ts
 declare function createPager<T extends Output>(filepath: string, options: PagerOptions & {
@@ -6,4 +6,4 @@ declare function createPager<T extends Output>(filepath: string, options: PagerO
 }): Pager<T>;
 declare function createPager(filepath: string, options?: PagerOptions): Pager<"string">;
 //#endregion
-export { type Pager, type PagerOptions, createNativePager, createPager, createPager as default };
+export { type Pager, type PagerOptions, createNativePager, createPager };

package/dist/main.mjs

@@ -152,30 +152,33 @@ function createBackwardReader(filepath, options) {
 			pageQueue.wake();
 			return;
 		}
-		while (!done && !closed) {
-			while (pageQueue.count < prefetch && pos > 0 && !closed) {
-				const readSize = Math.min(chunkSize, pos);
-				pos -= readSize;
-				const buf = Buffer.allocUnsafe(readSize);
-				const { bytesRead } = await fd.read(buf, 0, readSize, pos);
-				if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
-				else {
-					buffer = buf.toString("utf8", 0, bytesRead) + buffer;
-					if (pos === 0 && buffer.startsWith(delimiter)) startsWithDelimiter = true;
-					consumeBuffer();
+		try {
+			while (!done && !closed) {
+				while (pageQueue.count < prefetch && pos > 0 && !closed) {
+					const readSize = Math.min(chunkSize, pos);
+					pos -= readSize;
+					const buf = Buffer.allocUnsafe(readSize);
+					const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+					if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
+					else {
+						buffer = buf.toString("utf8", 0, bytesRead) + buffer;
+						if (pos === 0 && buffer.startsWith(delimiter)) startsWithDelimiter = true;
+						consumeBuffer();
+					}
 				}
-			}
-			if (pos === 0 && !flushed) {
-				flushTail();
-				if (fd) {
-					try {
-						await fd.close();
-					} catch {}
-					fd = null;
+				if (pos === 0 && !flushed) {
+					flushTail();
+					break;
 				}
-				break;
+				if (!done && !closed) await new Promise((r) => setImmediate(r));
+			}
+		} finally {
+			if (fd) {
+				try {
+					await fd.close();
+				} catch {}
+				fd = null;
 			}
-			if (!done && !closed) await new Promise((r) => setImmediate(r));
 		}
 	})();
 	function fillSync() {
@@ -261,13 +264,29 @@ function createBackwardReader(filepath, options) {
 					} catch {}
 					fdSync = null;
 				}
-				if (fd?.fd) {
-					try {
-						closeSync(fd.fd);
-					} catch {}
+				if (fd) {
+					fd.close().catch(() => {});
 					fd = null;
 				}
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			closed = true;
+			done = true;
+			pageQueue.clear();
+			if (fdSync) {
+				try {
+					closeSync(fdSync);
+				} catch {}
+				fdSync = null;
+			}
+			if (fd) {
+				fd.close().catch(() => {});
+				fd = null;
+			}
 		}
 	};
 }
@@ -333,29 +352,32 @@ function createForwardReader(filepath, options) {
 			pageQueue.wake();
 			return;
 		}
-		while (!done && !closed) {
-			while (pageQueue.count < prefetch && pos < size && !closed) {
-				const readSize = Math.min(chunkSize, size - pos);
-				const buf = Buffer.allocUnsafe(readSize);
-				const { bytesRead } = await fd.read(buf, 0, readSize, pos);
-				pos += bytesRead;
-				if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
-				else {
-					buffer = buffer + buf.toString("utf8", 0, bytesRead);
-					consumeBuffer();
+		try {
+			while (!done && !closed) {
+				while (pageQueue.count < prefetch && pos < size && !closed) {
+					const readSize = Math.min(chunkSize, size - pos);
+					const buf = Buffer.allocUnsafe(readSize);
+					const { bytesRead } = await fd.read(buf, 0, readSize, pos);
+					pos += bytesRead;
+					if (isBufferOutput) pageQueue.push(buf.subarray(0, bytesRead));
+					else {
+						buffer = buffer + buf.toString("utf8", 0, bytesRead);
+						consumeBuffer();
+					}
 				}
-			}
-			if (pos >= size && !flushed) {
-				flushTail();
-				if (fd) {
-					try {
-						await fd.close();
-					} catch {}
-					fd = null;
+				if (pos >= size && !flushed) {
+					flushTail();
+					break;
 				}
-				break;
+				if (!done && !closed) await new Promise((r) => setImmediate(r));
+			}
+		} finally {
+			if (fd) {
+				try {
+					await fd.close();
+				} catch {}
+				fd = null;
 			}
-			if (!done && !closed) await new Promise((r) => setImmediate(r));
 		}
 	})();
 	function fillSync() {
@@ -440,13 +462,29 @@ function createForwardReader(filepath, options) {
 					} catch {}
 					fdSync = null;
 				}
-				if (fd?.fd) {
-					try {
-						closeSync(fd.fd);
-					} catch {}
+				if (fd) {
+					fd.close().catch(() => {});
 					fd = null;
 				}
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			closed = true;
+			done = true;
+			pageQueue.clear();
+			if (fdSync) {
+				try {
+					closeSync(fdSync);
+				} catch {}
+				fdSync = null;
+			}
+			if (fd) {
+				fd.close().catch(() => {});
+				fd = null;
+			}
 		}
 	};
 }
@@ -464,12 +502,7 @@ function createPager(filepath, options = {}) {
 		delimiter,
 		output
 	};
-	const reader = backward ? createBackwardReader(filepath, readerOptions) : createForwardReader(filepath, readerOptions);
-	if (process.env.PAGER_TEST_CLEANUPS) {
-		globalThis.__pager_test_cleanups__ ??= [];
-		globalThis.__pager_test_cleanups__.push(reader.close);
-	}
-	return reader;
+	return backward ? createBackwardReader(filepath, readerOptions) : createForwardReader(filepath, readerOptions);
 }
 //#endregion
-export { createNativePager, createPager, createPager as default };
+export { createNativePager, createPager };

package/dist/{native-7FzZtBp1.d.cts → native-BJ3yhPgn.d.cts}

@@ -23,6 +23,8 @@ interface Pager<T extends Output = "string"> {
   close(): Promise<void>;
   [Symbol.asyncIterator](): AsyncIterator<ResolvePageOutput<T>>;
   [Symbol.iterator](): Iterator<ResolvePageOutput<T>>;
+  [Symbol.asyncDispose](): Promise<void>;
+  [Symbol.dispose](): void;
 }
 //#endregion
 //#region src/native.d.ts

package/dist/{native-B0PXEEYw.d.mts → native-BJ3yhPgn.d.mts}

@@ -23,6 +23,8 @@ interface Pager<T extends Output = "string"> {
   close(): Promise<void>;
   [Symbol.asyncIterator](): AsyncIterator<ResolvePageOutput<T>>;
   [Symbol.iterator](): Iterator<ResolvePageOutput<T>>;
+  [Symbol.asyncDispose](): Promise<void>;
+  [Symbol.dispose](): void;
 }
 //#endregion
 //#region src/native.d.ts

package/dist/native.cjs

@@ -34,10 +34,6 @@ function createNativePager(filepath, options = {}) {
 	if (delimiter?.length > 1) throw new RangeError("native reader only supports single-character delimiters");
 	const nativeReader = loadNativeAddon();
 	const isBufferOutput = output === "buffer";
-	if (process.env.PAGER_TEST_CLEANUPS) {
-		globalThis.__pager_test_cleanups__ ??= [];
-		globalThis.__pager_test_cleanups__.push(nativeReader.close);
-	}
 	let fd = nativeReader.open(filepath, pageSize, delimiter, backward);
 	let closed = false;
 	async function next() {
@@ -90,6 +86,12 @@ function createNativePager(filepath, options = {}) {
 			} finally {
 				tryClose();
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			tryClose();
 		}
 	};
 }

package/dist/native.d.cts

@@ -1,2 +1,2 @@
-import { t as createNativePager } from "./native-7FzZtBp1.cjs";
+import { t as createNativePager } from "./native-BJ3yhPgn.cjs";
 export { createNativePager };

package/dist/native.d.mts

@@ -1,2 +1,2 @@
-import { t as createNativePager } from "./native-B0PXEEYw.mjs";
+import { t as createNativePager } from "./native-BJ3yhPgn.mjs";
 export { createNativePager };

package/dist/native.mjs

@@ -33,10 +33,6 @@ function createNativePager(filepath, options = {}) {
 	if (delimiter?.length > 1) throw new RangeError("native reader only supports single-character delimiters");
 	const nativeReader = loadNativeAddon();
 	const isBufferOutput = output === "buffer";
-	if (process.env.PAGER_TEST_CLEANUPS) {
-		globalThis.__pager_test_cleanups__ ??= [];
-		globalThis.__pager_test_cleanups__.push(nativeReader.close);
-	}
 	let fd = nativeReader.open(filepath, pageSize, delimiter, backward);
 	let closed = false;
 	async function next() {
@@ -89,6 +85,12 @@ function createNativePager(filepath, options = {}) {
 			} finally {
 				tryClose();
 			}
+		},
+		[Symbol.asyncDispose]() {
+			return close();
+		},
+		[Symbol.dispose]() {
+			tryClose();
 		}
 	};
 }

package/package.json

@@ -1,35 +1,32 @@
 {
   "name": "readline-pager",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "scripts": {
     "build:js": "tsdown",
     "build:native": "node-gyp rebuild",
     "build": "npm run build:native && npm run build:js",
-    "pretest": "npm run build",
-    "test": "PAGER_TEST_CLEANUPS=1 c8 --reporter=lcov --reporter=text node --test test/**/*.test.ts",
+    "test": "./scripts/test.sh",
     "test:coverage": "npx lcov-badge2 coverage/lcov.info -o coverage.svg",
-    "prepublishOnly": "npm run build && npm run test",
-    "benchmark:node": "node test/benchmark.ts",
-    "benchmark:deno": "deno --allow-write --allow-read --allow-env test/benchmark.ts",
-    "benchmark:bun": "bun test/benchmark.ts"
+    "prepublishOnly": "npm run test",
+    "benchmark": "./scripts/benchmark.sh",
+    "prettier": "npx prettier -wu './(src|test)/**/*.{js,cjs,mjs,ts,cts,mts,json,yml,md}'"
   },
   "devDependencies": {
-    "@types/bun": "~1.3.13",
-    "@types/deno": "~2.5.0",
-    "@types/node": "~25.6.2",
-    "c8": "~11.0.0",
+    "@types/bun": "~1.3.14",
+    "@types/deno": "~2.7.0",
+    "@types/node": "~26.0.0",
     "lcov-badge2": "~1.1.4",
-    "node-gyp": "~12.3.0",
-    "prettier": "~3.8.3",
+    "node-gyp": "~13.0.0",
+    "prettier": "~3.8.4",
     "prettier-plugin-organize-imports": "~4.3.0",
-    "tsdown": "~0.22.0",
+    "tsdown": "~0.22.3",
     "typescript": "~6.0.3"
   },
   "optionalDependencies": {
-    "@devmor-j/readline-pager-linux-arm64": "0.7.3",
-    "@devmor-j/readline-pager-linux-musl-arm64": "0.7.3",
-    "@devmor-j/readline-pager-linux-musl-x64": "0.7.3",
-    "@devmor-j/readline-pager-linux-x64": "0.7.3"
+    "@devmor-j/readline-pager-linux-arm64": "0.8.0",
+    "@devmor-j/readline-pager-linux-musl-arm64": "0.8.0",
+    "@devmor-j/readline-pager-linux-musl-x64": "0.8.0",
+    "@devmor-j/readline-pager-linux-x64": "0.8.0"
   },
   "gypfile": false,
   "type": "module",