rrdir 14.1.2 → 14.2.0

package/README.md

@@ -1,11 +1,19 @@
 # rrdir
 [![](https://img.shields.io/npm/v/rrdir.svg?style=flat)](https://www.npmjs.org/package/rrdir) [![](https://img.shields.io/npm/dm/rrdir.svg)](https://www.npmjs.org/package/rrdir) [![](https://packagephobia.com/badge?p=rrdir)](https://packagephobia.com/result?p=rrdir) [![](https://depx.co/api/badge/rrdir)](https://depx.co/pkg/rrdir)
 
-> Recursive directory reader with a delightful API
-
 `rrdir` recursively reads a directory and returns entries within via an async iterator or async/sync as Array. It can typically iterate millions of files in a matter of seconds. Memory usage is `O(1)` for the async iterator and `O(n)` for the Array variants.
 
-Contrary to other similar modules, this module is optionally able to read any path including ones that contain invalid UTF-8 sequences.
+This module is able to read any path including ones that contain invalid UTF-8 sequences.
+
+| Benchmark | rrdir | fdir |
+|---|---|---|
+| async | 64ms | 57ms |
+| sync | 154ms | 178ms |
+| async + exclude | 46ms | — |
+| sync + exclude | 120ms | — |
+| async iterator | 319ms | — |
+
+Results for 122K entries (111K files, 11K dirs), Node.js on macOS. rrdir returns richer entries (path + directory + symlink) while fdir returns only paths. Run with `make bench`.
 
 ## Usage
 ```console

package/dist/index.d.ts

@@ -11,12 +11,6 @@ type RRDirOpts = {
   exclude?: Array<string>;
   insensitive?: boolean;
 };
-type Matcher = ((path: string) => boolean) | null;
-type InternalOpts = {
-  includeMatcher: Matcher;
-  excludeMatcher: Matcher;
-  encoding: Encoding;
-};
 type Entry<T = Dir> = {
   /** The path to the entry, will be relative if `dir` is given relative. If `dir` is a `Uint8Array`, this will be too. Always present. */path: T; /** Boolean indicating whether the entry is a directory. `undefined` on error. */
   directory?: boolean; /** Boolean indicating whether the entry is a symbolic link. `undefined` on error. */
@@ -24,7 +18,7 @@ type Entry<T = Dir> = {
   stats?: Stats; /** Any error encountered while reading this entry. `undefined` on success. */
   err?: Error;
 };
-declare function rrdir<T extends Dir>(dir: T, opts?: RRDirOpts, internalOpts?: InternalOpts): AsyncGenerator<Entry<T>>;
+declare function rrdir<T extends Dir>(dir: T, opts?: RRDirOpts): AsyncGenerator<Entry<T>>;
 declare function rrdirAsync<T extends Dir>(dir: T, opts?: RRDirOpts): Promise<Array<Entry<T>>>;
 declare function rrdirSync<T extends Dir>(dir: T, opts?: RRDirOpts): Array<Entry<T>>;
 //#endregion

package/dist/index.js

@@ -1,6 +1,6 @@
 import { lstat, readdir, stat } from "node:fs/promises";
 import { lstatSync, readdirSync, statSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 
 //#region index.ts
 const encoder = new TextEncoder();
@@ -30,13 +30,13 @@ function makePath({ name }, dir, encoding) {
 		return result;
 	} else return dir === "." ? name : `${dir}${sep}${name}`;
 }
-function build(dirent, path, stats, opts) {
+function build(path, isDir, isSym, stats, needStats) {
 	const entry = {
 		path,
-		directory: (stats || dirent).isDirectory(),
-		symlink: (stats || dirent).isSymbolicLink()
+		directory: stats ? stats.isDirectory() : isDir,
+		symlink: stats ? stats.isSymbolicLink() : isSym
 	};
-	if (opts.stats) entry.stats = stats;
+	if (needStats) entry.stats = stats;
 	return entry;
 }
 function globToRegex(pattern, insensitive) {
@@ -52,9 +52,10 @@ function globToRegex(pattern, insensitive) {
 function createMatcher(patterns, insensitive) {
 	if (!patterns?.length) return null;
 	const regexes = patterns.map((pattern) => globToRegex(pattern, insensitive));
+	const cwdPrefix = resolve(".") + sep;
 	return (path) => {
-		const resolved = resolve(path);
-		const normalizedPath = isWindows ? resolved.replace(/\\/g, "/") : resolved;
+		const absolute = isAbsolute(path) ? path : cwdPrefix + path;
+		const normalizedPath = isWindows ? absolute.replace(/\\/g, "/") : absolute;
 		return regexes.some((regex) => regex.test(normalizedPath));
 	};
 }
@@ -78,24 +79,62 @@ function initOpts(dir, opts) {
 		internalOpts: {
 			includeMatcher,
 			excludeMatcher,
-			encoding
+			hasMatcher: Boolean(excludeMatcher || includeMatcher),
+			encoding,
+			followSymlinks: Boolean(opts.followSymlinks),
+			needStats: Boolean(opts.stats),
+			strict: Boolean(opts.strict),
+			readdirOpts: {
+				encoding,
+				withFileTypes: true
+			}
 		}
 	};
 }
 function getStringPath(path, encoding) {
 	return encoding === "buffer" ? toString(path) : path;
 }
-async function* rrdir(dir, opts = {}, internalOpts) {
-	if (!internalOpts) ({dir, opts, internalOpts} = initOpts(dir, opts));
-	const { includeMatcher, excludeMatcher, encoding } = internalOpts;
+async function* rrdir(dir, opts = {}) {
+	const init = initOpts(dir, opts);
+	const { hasMatcher, encoding, followSymlinks, needStats, strict, readdirOpts } = init.internalOpts;
+	dir = init.dir;
+	if (!hasMatcher && !followSymlinks && !needStats) {
+		const stack = [dir];
+		while (stack.length > 0) {
+			const currentDir = stack.pop();
+			let dirents;
+			try {
+				dirents = await readdir(currentDir, readdirOpts);
+			} catch (err) {
+				if (strict) throw err;
+				yield {
+					path: currentDir,
+					err
+				};
+				continue;
+			}
+			for (const dirent of dirents) {
+				const path = makePath(dirent, currentDir, encoding);
+				const isDir = dirent.isDirectory();
+				yield {
+					path,
+					directory: isDir,
+					symlink: dirent.isSymbolicLink()
+				};
+				if (isDir) stack.push(path);
+			}
+		}
+		return;
+	}
+	yield* rrdirInner(dir, init.opts, init.internalOpts);
+}
+async function* rrdirInner(dir, opts, internalOpts) {
+	const { includeMatcher, excludeMatcher, hasMatcher, encoding, followSymlinks, needStats, strict, readdirOpts } = internalOpts;
 	let dirents = [];
 	try {
-		dirents = await readdir(dir, {
-			encoding,
-			withFileTypes: true
-		});
+		dirents = await readdir(dir, readdirOpts);
 	} catch (err) {
-		if (opts.strict) throw err;
+		if (strict) throw err;
 		yield {
 			path: dir,
 			err
@@ -104,31 +143,36 @@ async function* rrdir(dir, opts = {}, internalOpts) {
 	if (!dirents.length) return;
 	for (const dirent of dirents) {
 		const path = makePath(dirent, dir, encoding);
-		const stringPath = getStringPath(path, encoding);
-		if (excludeMatcher?.(stringPath)) continue;
-		const isSymbolicLink = Boolean(opts.followSymlinks && dirent.isSymbolicLink());
-		const isIncluded = !includeMatcher || includeMatcher(stringPath);
+		let isIncluded = true;
+		if (hasMatcher) {
+			const stringPath = getStringPath(path, encoding);
+			if (excludeMatcher?.(stringPath)) continue;
+			isIncluded = !includeMatcher || includeMatcher(stringPath);
+		}
+		const isDir = dirent.isDirectory();
+		const isSym = dirent.isSymbolicLink();
+		const isFollowedSym = followSymlinks && isSym;
 		let stats;
 		if (isIncluded) {
-			if (opts.stats || isSymbolicLink) try {
-				stats = await (opts.followSymlinks ? stat : lstat)(path);
+			if (needStats || isFollowedSym) try {
+				stats = await (followSymlinks ? stat : lstat)(path);
 			} catch (err) {
-				if (opts.strict) throw err;
+				if (strict) throw err;
 				yield {
 					path,
 					err
 				};
 			}
-			yield build(dirent, path, stats, opts);
+			yield build(path, isDir, isSym, stats, needStats);
 		}
-		let recurse = false;
-		if (isSymbolicLink) {
+		let recurse = isDir;
+		if (isFollowedSym) {
 			if (!stats) try {
 				stats = await stat(path);
 			} catch {}
-			if (stats?.isDirectory()) recurse = true;
-		} else if (dirent.isDirectory()) recurse = true;
-		if (recurse) yield* rrdir(path, opts, internalOpts);
+			recurse = Boolean(stats?.isDirectory());
+		}
+		if (recurse) yield* rrdirInner(path, opts, internalOpts);
 	}
 }
 async function rrdirAsync(dir, opts = {}) {
@@ -138,49 +182,53 @@ async function rrdirAsync(dir, opts = {}) {
 	return results;
 }
 async function rrdirAsyncInner(dir, opts, internalOpts, results) {
-	const { includeMatcher, excludeMatcher, encoding } = internalOpts;
+	const { includeMatcher, excludeMatcher, hasMatcher, encoding, followSymlinks, needStats, strict, readdirOpts } = internalOpts;
 	let dirents = [];
 	try {
-		dirents = await readdir(dir, {
-			encoding,
-			withFileTypes: true
-		});
+		dirents = await readdir(dir, readdirOpts);
 	} catch (err) {
-		if (opts.strict) throw err;
+		if (strict) throw err;
 		results.push({
 			path: dir,
 			err
 		});
 	}
 	if (!dirents.length) return;
-	await Promise.all(dirents.map(async (dirent) => {
+	const pendingDirs = [];
+	for (const dirent of dirents) {
 		const path = makePath(dirent, dir, encoding);
-		const stringPath = getStringPath(path, encoding);
-		if (excludeMatcher?.(stringPath)) return;
-		const isSymbolicLink = Boolean(opts.followSymlinks && dirent.isSymbolicLink());
-		const isIncluded = !includeMatcher || includeMatcher(stringPath);
+		let isIncluded = true;
+		if (hasMatcher) {
+			const stringPath = getStringPath(path, encoding);
+			if (excludeMatcher?.(stringPath)) continue;
+			isIncluded = !includeMatcher || includeMatcher(stringPath);
+		}
+		const isDir = dirent.isDirectory();
+		const isSym = dirent.isSymbolicLink();
+		const isFollowedSym = followSymlinks && isSym;
 		let stats;
 		if (isIncluded) {
-			if (opts.stats || isSymbolicLink) try {
-				stats = await (opts.followSymlinks ? stat : lstat)(path);
+			if (needStats || isFollowedSym) try {
+				stats = await (followSymlinks ? stat : lstat)(path);
 			} catch (err) {
-				if (opts.strict) throw err;
+				if (strict) throw err;
 				results.push({
 					path,
 					err
 				});
 			}
-			results.push(build(dirent, path, stats, opts));
+			results.push(build(path, isDir, isSym, stats, needStats));
 		}
-		let recurse = false;
-		if (isSymbolicLink) {
+		let recurse = isDir;
+		if (isFollowedSym) {
 			if (!stats) try {
 				stats = await stat(path);
 			} catch {}
-			if (stats?.isDirectory()) recurse = true;
-		} else if (dirent.isDirectory()) recurse = true;
-		if (recurse) await rrdirAsyncInner(path, opts, internalOpts, results);
-	}));
+			recurse = Boolean(stats?.isDirectory());
+		}
+		if (recurse) pendingDirs.push(path);
+	}
+	if (pendingDirs.length) await Promise.all(pendingDirs.map((p) => rrdirAsyncInner(p, opts, internalOpts, results)));
 }
 function rrdirSync(dir, opts = {}) {
 	const init = initOpts(dir, opts);
@@ -189,15 +237,12 @@ function rrdirSync(dir, opts = {}) {
 	return results;
 }
 function rrdirSyncInner(dir, opts, internalOpts, results) {
-	const { includeMatcher, excludeMatcher, encoding } = internalOpts;
+	const { includeMatcher, excludeMatcher, hasMatcher, encoding, followSymlinks, needStats, strict, readdirOpts } = internalOpts;
 	let dirents = [];
 	try {
-		dirents = readdirSync(dir, {
-			encoding,
-			withFileTypes: true
-		});
+		dirents = readdirSync(dir, readdirOpts);
 	} catch (err) {
-		if (opts.strict) throw err;
+		if (strict) throw err;
 		results.push({
 			path: dir,
 			err
@@ -206,30 +251,35 @@ function rrdirSyncInner(dir, opts, internalOpts, results) {
 	if (!dirents.length) return;
 	for (const dirent of dirents) {
 		const path = makePath(dirent, dir, encoding);
-		const stringPath = getStringPath(path, encoding);
-		if (excludeMatcher?.(stringPath)) continue;
-		const isSymbolicLink = Boolean(opts.followSymlinks && dirent.isSymbolicLink());
-		const isIncluded = !includeMatcher || includeMatcher(stringPath);
+		let isIncluded = true;
+		if (hasMatcher) {
+			const stringPath = getStringPath(path, encoding);
+			if (excludeMatcher?.(stringPath)) continue;
+			isIncluded = !includeMatcher || includeMatcher(stringPath);
+		}
+		const isDir = dirent.isDirectory();
+		const isSym = dirent.isSymbolicLink();
+		const isFollowedSym = followSymlinks && isSym;
 		let stats;
 		if (isIncluded) {
-			if (opts.stats || isSymbolicLink) try {
-				stats = (opts.followSymlinks ? statSync : lstatSync)(path);
+			if (needStats || isFollowedSym) try {
+				stats = (followSymlinks ? statSync : lstatSync)(path);
 			} catch (err) {
-				if (opts.strict) throw err;
+				if (strict) throw err;
 				results.push({
 					path,
 					err
 				});
 			}
-			results.push(build(dirent, path, stats, opts));
+			results.push(build(path, isDir, isSym, stats, needStats));
 		}
-		let recurse = false;
-		if (isSymbolicLink) {
+		let recurse = isDir;
+		if (isFollowedSym) {
 			if (!stats) try {
 				stats = statSync(path);
 			} catch {}
-			if (stats?.isDirectory()) recurse = true;
-		} else if (dirent.isDirectory()) recurse = true;
+			recurse = Boolean(stats?.isDirectory());
+		}
 		if (recurse) rrdirSyncInner(path, opts, internalOpts, results);
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rrdir",
-  "version": "14.1.2",
+  "version": "14.2.0",
   "description": "Recursive directory reader with a delightful API",
   "author": "silverwind <me@silverwind.io>",
   "repository": "silverwind/rrdir",
@@ -17,19 +17,20 @@
     "node": ">=22"
   },
   "devDependencies": {
-    "@types/node": "25.1.0",
-    "@typescript/native-preview": "7.0.0-dev.20260212.1",
-    "eslint": "9.39.2",
-    "eslint-config-silverwind": "120.1.2",
+    "@types/node": "25.3.5",
+    "@typescript/native-preview": "7.0.0-dev.20260306.1",
+    "eslint": "9.39.3",
+    "eslint-config-silverwind": "122.0.6",
+    "fdir": "6.5.0",
     "jest-extended": "7.0.0",
-    "tsdown": "0.20.1",
-    "tsdown-config-silverwind": "1.7.3",
+    "tsdown": "0.21.0",
+    "tsdown-config-silverwind": "2.0.0",
     "typescript": "5.9.3",
-    "typescript-config-silverwind": "14.0.0",
-    "updates": "17.0.8",
+    "typescript-config-silverwind": "15.0.0",
+    "updates": "17.8.2",
     "updates-config-silverwind": "1.0.3",
-    "versions": "14.0.3",
+    "versions": "14.2.1",
     "vitest": "4.0.18",
-    "vitest-config-silverwind": "10.6.1"
+    "vitest-config-silverwind": "10.6.3"
   }
 }