readline-pager 0.4.9 → 0.5.1

package/README.md

@@ -85,6 +85,7 @@ createPager(filepath, {
   prefetch?: number,    // default: 8
   backward?: boolean,   // default: false
   useWorker?: boolean,  // default: false
+  tryNative?: boolean,  // default: true
 });
 ```
 
@@ -94,6 +95,10 @@ createPager(filepath, {
 - `prefetch` — maximum number of pages buffered internally.
 - `backward` — read the file from end to start.
 - `useWorker` — offload reading to a worker thread (forward reading only).
+- `tryNative` — attempts to use the native reader, falls back to the non-native version if it fails.
+
+> **Note:**
+> `createNativePager` supports only `pageSize`, `delimiter`, and `backward` options and does **not** support multi-character delimiters.
 
 ---
 
@@ -107,7 +112,11 @@ Returns `null` when the end of the file is reached.
 
 Empty lines are preserved.
 
----
+> **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.
 
 ### `pager.nextSync(): string[] | null`
 
@@ -115,30 +124,12 @@ Synchronous version of `pager.next()`.
 
 Returns the next page immediately or `null` when the end of the file is reached.
 
----
-
 ### `pager.close(): Promise<void>`
 
 Stops reading and releases resources asynchronously. Safe to call at any time.
 
 ---
 
-### `createNativePager(filepath, options?): Pager`
-
-Creates a pager backed by the optional native C++ addon.
-
-If the native addon is not available for the current platform, this function throws.
-
----
-
-> **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.
-
----
-
 ## 📊 Benchmark
 
 Run the benchmark locally:

package/dist/main.cjs

@@ -532,18 +532,35 @@ function createWorkerReader(filepath, options) {
 //#endregion
 //#region src/main.ts
 function createPager(filepath, options = {}) {
-	const { chunkSize = 64 * 1024, pageSize = 1e3, delimiter = "\n", prefetch = 8, backward = false, useWorker = false } = options;
+	const { chunkSize = 64 * 1024, pageSize = 1e3, delimiter = "\n", prefetch = 8, backward = false, useWorker = false, tryNative = true } = options;
 	if (!filepath) throw new Error("filepath required");
 	if (pageSize < 1) throw new RangeError("pageSize must be >= 1");
 	if (prefetch < 1) throw new RangeError("prefetch must be >= 1");
-	if (backward && useWorker) throw new Error("backward not supported with useWorker");
+	if (useWorker) {
+		if (backward) throw new Error("backward not supported with useWorker");
+		if (tryNative) throw new Error("tryNative not supported with useWorker");
+	}
+	if (tryNative) {
+		if (delimiter.length !== 1) throw new RangeError("native reader only supports single-character delimiters");
+	}
 	const _options = {
 		chunkSize,
 		pageSize,
 		prefetch,
 		delimiter
 	};
-	const reader = useWorker ? createWorkerReader(filepath, _options) : backward ? createBackwardReader(filepath, _options) : createForwardReader(filepath, _options);
+	let nativeReader;
+	if (tryNative) {
+		const _nativeOptions = {
+			pageSize,
+			delimiter,
+			backward
+		};
+		try {
+			nativeReader = require_native.createNativePager(filepath, _nativeOptions);
+		} catch {}
+	}
+	const reader = tryNative && nativeReader ? nativeReader : useWorker ? createWorkerReader(filepath, _options) : backward ? createBackwardReader(filepath, _options) : createForwardReader(filepath, _options);
 	if (process.env.TEST_CLEANUPS) {
 		globalThis.__test_cleanups__ ??= [];
 		globalThis.__test_cleanups__.push(reader.close);

package/dist/main.d.cts

@@ -1,6 +1,6 @@
-import { i as ReaderOptions, n as Pager, r as PagerOptions, t as createNativePager } from "./native-BNwCco1j.cjs";
+import { a as NativeReaderOptions, c as ReaderOptions, i as NativeAddon, n as AddonData, o as Pager, r as AddonFD, s as PagerOptions, t as createNativePager } from "./native-46pCT8Rc.cjs";
 
 //#region src/main.d.ts
 declare function createPager(filepath: string, options?: PagerOptions): Pager;
 //#endregion
-export { Pager, PagerOptions, ReaderOptions, createNativePager, createPager, createPager as default };
+export { AddonData, AddonFD, NativeAddon, NativeReaderOptions, Pager, PagerOptions, ReaderOptions, createNativePager, createPager, createPager as default };

package/dist/main.d.mts

@@ -1,6 +1,6 @@
-import { i as ReaderOptions, n as Pager, r as PagerOptions, t as createNativePager } from "./native-BWytCdQz.mjs";
+import { a as NativeReaderOptions, c as ReaderOptions, i as NativeAddon, n as AddonData, o as Pager, r as AddonFD, s as PagerOptions, t as createNativePager } from "./native-DeBXdY3U.mjs";
 
 //#region src/main.d.ts
 declare function createPager(filepath: string, options?: PagerOptions): Pager;
 //#endregion
-export { Pager, PagerOptions, ReaderOptions, createNativePager, createPager, createPager as default };
+export { AddonData, AddonFD, NativeAddon, NativeReaderOptions, Pager, PagerOptions, ReaderOptions, createNativePager, createPager, createPager as default };

package/dist/main.mjs

@@ -532,18 +532,35 @@ function createWorkerReader(filepath, options) {
 //#endregion
 //#region src/main.ts
 function createPager(filepath, options = {}) {
-	const { chunkSize = 64 * 1024, pageSize = 1e3, delimiter = "\n", prefetch = 8, backward = false, useWorker = false } = options;
+	const { chunkSize = 64 * 1024, pageSize = 1e3, delimiter = "\n", prefetch = 8, backward = false, useWorker = false, tryNative = true } = options;
 	if (!filepath) throw new Error("filepath required");
 	if (pageSize < 1) throw new RangeError("pageSize must be >= 1");
 	if (prefetch < 1) throw new RangeError("prefetch must be >= 1");
-	if (backward && useWorker) throw new Error("backward not supported with useWorker");
+	if (useWorker) {
+		if (backward) throw new Error("backward not supported with useWorker");
+		if (tryNative) throw new Error("tryNative not supported with useWorker");
+	}
+	if (tryNative) {
+		if (delimiter.length !== 1) throw new RangeError("native reader only supports single-character delimiters");
+	}
 	const _options = {
 		chunkSize,
 		pageSize,
 		prefetch,
 		delimiter
 	};
-	const reader = useWorker ? createWorkerReader(filepath, _options) : backward ? createBackwardReader(filepath, _options) : createForwardReader(filepath, _options);
+	let nativeReader;
+	if (tryNative) {
+		const _nativeOptions = {
+			pageSize,
+			delimiter,
+			backward
+		};
+		try {
+			nativeReader = createNativePager(filepath, _nativeOptions);
+		} catch {}
+	}
+	const reader = tryNative && nativeReader ? nativeReader : useWorker ? createWorkerReader(filepath, _options) : backward ? createBackwardReader(filepath, _options) : createForwardReader(filepath, _options);
 	if (process.env.TEST_CLEANUPS) {
 		globalThis.__test_cleanups__ ??= [];
 		globalThis.__test_cleanups__.push(reader.close);

package/dist/native-46pCT8Rc.d.cts

@@ -0,0 +1,35 @@
+//#region src/types.d.ts
+interface ReaderOptions {
+  chunkSize: number;
+  pageSize: number;
+  delimiter: string;
+  prefetch: number;
+}
+interface PagerOptions extends Partial<ReaderOptions> {
+  backward?: boolean;
+  useWorker?: boolean;
+  tryNative?: boolean;
+}
+interface Pager extends AsyncIterable<string[]>, Iterable<string[]> {
+  next(): Promise<string[] | null>;
+  nextSync(): string[] | null;
+  close(): Promise<void>;
+}
+interface NativeReaderOptions {
+  pageSize: number;
+  delimiter: string;
+  backward: boolean;
+}
+type AddonFD = object | null;
+type AddonData = Buffer | null;
+interface NativeAddon {
+  open: (filepath: string, pageSize: number, delimiter: string, backward: boolean) => AddonFD;
+  next: (fd: AddonFD) => Promise<AddonData>;
+  nextSync: (fd: AddonFD) => AddonData;
+  close: (fd: AddonFD) => Promise<void>;
+}
+//#endregion
+//#region src/native.d.ts
+declare function createNativePager(filepath: string, options?: Partial<NativeReaderOptions>): Pager;
+//#endregion
+export { NativeReaderOptions as a, ReaderOptions as c, NativeAddon as i, AddonData as n, Pager as o, AddonFD as r, PagerOptions as s, createNativePager as t };

package/dist/native-DeBXdY3U.d.mts

@@ -0,0 +1,35 @@
+//#region src/types.d.ts
+interface ReaderOptions {
+  chunkSize: number;
+  pageSize: number;
+  delimiter: string;
+  prefetch: number;
+}
+interface PagerOptions extends Partial<ReaderOptions> {
+  backward?: boolean;
+  useWorker?: boolean;
+  tryNative?: boolean;
+}
+interface Pager extends AsyncIterable<string[]>, Iterable<string[]> {
+  next(): Promise<string[] | null>;
+  nextSync(): string[] | null;
+  close(): Promise<void>;
+}
+interface NativeReaderOptions {
+  pageSize: number;
+  delimiter: string;
+  backward: boolean;
+}
+type AddonFD = object | null;
+type AddonData = Buffer | null;
+interface NativeAddon {
+  open: (filepath: string, pageSize: number, delimiter: string, backward: boolean) => AddonFD;
+  next: (fd: AddonFD) => Promise<AddonData>;
+  nextSync: (fd: AddonFD) => AddonData;
+  close: (fd: AddonFD) => Promise<void>;
+}
+//#endregion
+//#region src/native.d.ts
+declare function createNativePager(filepath: string, options?: Partial<NativeReaderOptions>): Pager;
+//#endregion
+export { NativeReaderOptions as a, ReaderOptions as c, NativeAddon as i, AddonData as n, Pager as o, AddonFD as r, PagerOptions as s, createNativePager as t };

package/dist/native.cjs

@@ -29,29 +29,33 @@ function loadNativeAddon() {
 		throw new Error(UNAVAILABLE);
 	}
 }
-function createNativePager(filepath, { pageSize = 1e3, delimiter = "\n" } = {}) {
-	const pagerNative = loadNativeAddon();
+function createNativePager(filepath, options) {
+	const { pageSize = 1e3, delimiter = "\n", backward = false } = options ?? {};
+	if (!filepath) throw new Error("filepath required");
+	if (pageSize < 1) throw new RangeError("pageSize must be >= 1");
+	if (delimiter.length !== 1) throw new RangeError("native reader only supports single-character delimiters");
+	const nativePager = loadNativeAddon();
 	let fd = null;
 	let closed = false;
 	const init = () => {
-		fd = pagerNative.open(filepath, pageSize, delimiter);
+		fd = nativePager.open(filepath, pageSize, delimiter, backward);
 	};
 	const next = async () => {
 		if (closed || !fd) return null;
-		const data = await pagerNative.next(fd);
+		const data = await nativePager.next(fd);
 		if (!data) return null;
 		return data.toString("utf8").split(delimiter);
 	};
 	const nextSync = () => {
 		if (closed || !fd) return null;
-		const data = pagerNative.nextSync(fd);
+		const data = nativePager.nextSync(fd);
 		if (!data) return null;
 		return data.toString("utf8").split(delimiter);
 	};
 	const close = async () => {
 		if (!closed || fd) {
 			closed = true;
-			await pagerNative.close(fd);
+			await nativePager.close(fd);
 			fd = null;
 		}
 	};

package/dist/native.d.cts

@@ -1,2 +1,2 @@
-import { t as createNativePager } from "./native-BNwCco1j.cjs";
+import { t as createNativePager } from "./native-46pCT8Rc.cjs";
 export { createNativePager };

package/dist/native.d.mts

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

package/dist/native.mjs

@@ -28,29 +28,33 @@ function loadNativeAddon() {
 		throw new Error(UNAVAILABLE);
 	}
 }
-function createNativePager(filepath, { pageSize = 1e3, delimiter = "\n" } = {}) {
-	const pagerNative = loadNativeAddon();
+function createNativePager(filepath, options) {
+	const { pageSize = 1e3, delimiter = "\n", backward = false } = options ?? {};
+	if (!filepath) throw new Error("filepath required");
+	if (pageSize < 1) throw new RangeError("pageSize must be >= 1");
+	if (delimiter.length !== 1) throw new RangeError("native reader only supports single-character delimiters");
+	const nativePager = loadNativeAddon();
 	let fd = null;
 	let closed = false;
 	const init = () => {
-		fd = pagerNative.open(filepath, pageSize, delimiter);
+		fd = nativePager.open(filepath, pageSize, delimiter, backward);
 	};
 	const next = async () => {
 		if (closed || !fd) return null;
-		const data = await pagerNative.next(fd);
+		const data = await nativePager.next(fd);
 		if (!data) return null;
 		return data.toString("utf8").split(delimiter);
 	};
 	const nextSync = () => {
 		if (closed || !fd) return null;
-		const data = pagerNative.nextSync(fd);
+		const data = nativePager.nextSync(fd);
 		if (!data) return null;
 		return data.toString("utf8").split(delimiter);
 	};
 	const close = async () => {
 		if (!closed || fd) {
 			closed = true;
-			await pagerNative.close(fd);
+			await nativePager.close(fd);
 			fd = null;
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "readline-pager",
-  "version": "0.4.9",
+  "version": "0.5.1",
   "scripts": {
     "build:js": "tsdown",
     "build:native": "node-gyp rebuild",
@@ -24,10 +24,10 @@
     "typescript": "~6.0.2"
   },
   "optionalDependencies": {
-    "@devmor-j/readline-pager-linux-arm64": "0.4.9",
-    "@devmor-j/readline-pager-linux-x64": "0.4.9",
-    "@devmor-j/readline-pager-linux-musl-arm64": "0.4.9",
-    "@devmor-j/readline-pager-linux-musl-x64": "0.4.9"
+    "@devmor-j/readline-pager-linux-arm64": "0.5.1",
+    "@devmor-j/readline-pager-linux-musl-arm64": "0.5.1",
+    "@devmor-j/readline-pager-linux-musl-x64": "0.5.1",
+    "@devmor-j/readline-pager-linux-x64": "0.5.1"
   },
   "gypfile": false,
   "type": "module",

package/dist/native-BNwCco1j.d.cts

@@ -1,27 +0,0 @@
-//#region src/types.d.ts
-interface ReaderOptions {
-  chunkSize: number;
-  pageSize: number;
-  delimiter: string;
-  prefetch: number;
-}
-interface PagerOptions extends Partial<ReaderOptions> {
-  backward?: boolean;
-  useWorker?: boolean;
-}
-interface Pager extends AsyncIterable<string[]>, Iterable<string[]> {
-  next(): Promise<string[] | null>;
-  nextSync(): string[] | null;
-  close(): Promise<void>;
-}
-//#endregion
-//#region src/native.d.ts
-declare function createNativePager(filepath: string, {
-  pageSize,
-  delimiter
-}?: {
-  pageSize?: number | undefined;
-  delimiter?: string | undefined;
-}): Pager;
-//#endregion
-export { ReaderOptions as i, Pager as n, PagerOptions as r, createNativePager as t };

package/dist/native-BWytCdQz.d.mts

@@ -1,27 +0,0 @@
-//#region src/types.d.ts
-interface ReaderOptions {
-  chunkSize: number;
-  pageSize: number;
-  delimiter: string;
-  prefetch: number;
-}
-interface PagerOptions extends Partial<ReaderOptions> {
-  backward?: boolean;
-  useWorker?: boolean;
-}
-interface Pager extends AsyncIterable<string[]>, Iterable<string[]> {
-  next(): Promise<string[] | null>;
-  nextSync(): string[] | null;
-  close(): Promise<void>;
-}
-//#endregion
-//#region src/native.d.ts
-declare function createNativePager(filepath: string, {
-  pageSize,
-  delimiter
-}?: {
-  pageSize?: number | undefined;
-  delimiter?: string | undefined;
-}): Pager;
-//#endregion
-export { ReaderOptions as i, Pager as n, PagerOptions as r, createNativePager as t };