Respect custom fs implementation from options

Fixes #265
Fixes #236
Fixes #189

Author: sindresorhus

ignore.js

@@ -6,7 +6,7 @@ import fastGlob from 'fast-glob';
 import gitIgnore from 'ignore';
 import slash from 'slash';
 import {toPath} from 'unicorn-magic';
-import {isNegativePattern} from './utilities.js';
+import {isNegativePattern, bindFsMethod} from './utilities.js';
 
 const defaultIgnoredDirectories = [
 	'**/node_modules',
@@ -21,6 +21,15 @@ const ignoreFilesGlobOptions = {
 
 export const GITIGNORE_FILES_PATTERN = '**/.gitignore';
 
+const getReadFileMethod = fsImplementation =>
+	bindFsMethod(fsImplementation?.promises, 'readFile')
+	?? bindFsMethod(fsImplementation, 'readFile')
+	?? bindFsMethod(fsPromises, 'readFile');
+
+const getReadFileSyncMethod = fsImplementation =>
+	bindFsMethod(fsImplementation, 'readFileSync')
+	?? bindFsMethod(fs, 'readFileSync');
+
 // Apply base path to gitignore patterns based on .gitignore spec 2.22.1
 // https://git-scm.com/docs/gitignore#_pattern_format
 // See also https://github.com/sindresorhus/globby/issues/146
@@ -119,7 +128,7 @@ const normalizeOptions = (options = {}) => {
 	// Adjust deep option for fast-glob: fast-glob's deep counts differently than expected
 	// User's deep: 0 = root only -> fast-glob needs: 1
 	// User's deep: 1 = root + 1 level -> fast-glob needs: 2
-	const deep = typeof options.deep === 'number' ? options.deep + 1 : Number.POSITIVE_INFINITY;
+	const deep = typeof options.deep === 'number' ? Math.max(0, options.deep) + 1 : Number.POSITIVE_INFINITY;
 
 	// Only pass through specific fast-glob options that make sense for finding ignore files
 	return {
@@ -130,6 +139,7 @@ const normalizeOptions = (options = {}) => {
 		followSymbolicLinks: options.followSymbolicLinks ?? true,
 		concurrency: options.concurrency,
 		throwErrorOnBrokenSymbolicLink: options.throwErrorOnBrokenSymbolicLink ?? false,
+		fs: options.fs,
 	};
 };
 
@@ -141,9 +151,10 @@ export const isIgnoredByIgnoreFiles = async (patterns, options) => {
 		...ignoreFilesGlobOptions, // Must be last to ensure absolute and dot are always set
 	});
 
+	const readFileMethod = getReadFileMethod(normalizedOptions.fs);
 	const files = await Promise.all(paths.map(async filePath => ({
 		filePath,
-		content: await fsPromises.readFile(filePath, 'utf8'),
+		content: await readFileMethod(filePath, 'utf8'),
 	})));
 
 	return getIsIgnoredPredicate(files, normalizedOptions.cwd);
@@ -157,9 +168,10 @@ export const isIgnoredByIgnoreFilesSync = (patterns, options) => {
 		...ignoreFilesGlobOptions, // Must be last to ensure absolute and dot are always set
 	});
 
+	const readFileSyncMethod = getReadFileSyncMethod(normalizedOptions.fs);
 	const files = paths.map(filePath => ({
 		filePath,
-		content: fs.readFileSync(filePath, 'utf8'),
+		content: readFileSyncMethod(filePath, 'utf8'),
 	}));
 
 	return getIsIgnoredPredicate(files, normalizedOptions.cwd);
@@ -181,9 +193,10 @@ export const getIgnorePatternsAndPredicate = async (patterns, options) => {
 		...ignoreFilesGlobOptions, // Must be last to ensure absolute and dot are always set
 	});
 
+	const readFileMethod = getReadFileMethod(normalizedOptions.fs);
 	const files = await Promise.all(paths.map(async filePath => ({
 		filePath,
-		content: await fsPromises.readFile(filePath, 'utf8'),
+		content: await readFileMethod(filePath, 'utf8'),
 	})));
 
 	return {
@@ -205,9 +218,10 @@ export const getIgnorePatternsAndPredicateSync = (patterns, options) => {
 		...ignoreFilesGlobOptions, // Must be last to ensure absolute and dot are always set
 	});
 
+	const readFileSyncMethod = getReadFileSyncMethod(normalizedOptions.fs);
 	const files = paths.map(filePath => ({
 		filePath,
-		content: fs.readFileSync(filePath, 'utf8'),
+		content: readFileSyncMethod(filePath, 'utf8'),
 	}));
 
 	return {

index.d.ts

@@ -120,6 +120,13 @@ export type GitignoreOptions = {
 	@default false
 	*/
 	readonly throwErrorOnBrokenSymbolicLink?: boolean;
+
+	/**
+	Custom file system implementation (useful for testing or virtual file systems).
+
+	@default undefined
+	*/
+	readonly fs?: FastGlob.Options['fs'];
 };
 
 export type GlobbyFilterFunction = (path: URL | string) => boolean;

index.js

@@ -4,14 +4,14 @@ import nodePath from 'node:path';
 import {Readable} from 'node:stream';
 import mergeStreams from '@sindresorhus/merge-streams';
 import fastGlob from 'fast-glob';
-import {isDirectory, isDirectorySync} from 'path-type';
 import {toPath} from 'unicorn-magic';
 import {
 	GITIGNORE_FILES_PATTERN,
 	getIgnorePatternsAndPredicate,
 	getIgnorePatternsAndPredicateSync,
 } from './ignore.js';
 import {
+	bindFsMethod,
 	isNegativePattern,
 	normalizeDirectoryPatternForFastGlob,
 } from './utilities.js';
@@ -22,6 +22,33 @@ const assertPatternsInput = patterns => {
 	}
 };
 
+const getStatMethod = fsImplementation =>
+	bindFsMethod(fsImplementation?.promises, 'stat')
+	?? bindFsMethod(fsImplementation, 'stat')
+	?? bindFsMethod(fs.promises, 'stat');
+
+const getStatSyncMethod = fsImplementation =>
+	bindFsMethod(fsImplementation, 'statSync')
+	?? bindFsMethod(fs, 'statSync');
+
+const isDirectory = async (path, fsImplementation) => {
+	try {
+		const stats = await getStatMethod(fsImplementation)(path);
+		return stats.isDirectory();
+	} catch {
+		return false;
+	}
+};
+
+const isDirectorySync = (path, fsImplementation) => {
+	try {
+		const stats = getStatSyncMethod(fsImplementation)(path);
+		return stats.isDirectory();
+	} catch {
+		return false;
+	}
+};
+
 const normalizePathForDirectoryGlob = (filePath, cwd) => {
 	const path = isNegativePattern(filePath) ? filePath.slice(1) : filePath;
 	return nodePath.isAbsolute(path) ? path : nodePath.join(cwd, path);
@@ -51,6 +78,7 @@ const directoryToGlob = async (directoryPaths, {
 	cwd = process.cwd(),
 	files,
 	extensions,
+	fs: fsImplementation,
 } = {}) => {
 	const globs = await Promise.all(directoryPaths.map(async directoryPath => {
 		// Check pattern without negative prefix
@@ -63,7 +91,7 @@ const directoryToGlob = async (directoryPaths, {
 
 		// Original logic for checking actual directories
 		const pathToCheck = normalizePathForDirectoryGlob(directoryPath, cwd);
-		return (await isDirectory(pathToCheck)) ? getDirectoryGlob({directoryPath, files, extensions}) : directoryPath;
+		return (await isDirectory(pathToCheck, fsImplementation)) ? getDirectoryGlob({directoryPath, files, extensions}) : directoryPath;
 	}));
 
 	return globs.flat();
@@ -73,6 +101,7 @@ const directoryToGlobSync = (directoryPaths, {
 	cwd = process.cwd(),
 	files,
 	extensions,
+	fs: fsImplementation,
 } = {}) => directoryPaths.flatMap(directoryPath => {
 	// Check pattern without negative prefix
 	const checkPattern = isNegativePattern(directoryPath) ? directoryPath.slice(1) : directoryPath;
@@ -84,7 +113,7 @@ const directoryToGlobSync = (directoryPaths, {
 
 	// Original logic for checking actual directories
 	const pathToCheck = normalizePathForDirectoryGlob(directoryPath, cwd);
-	return isDirectorySync(pathToCheck) ? getDirectoryGlob({directoryPath, files, extensions}) : directoryPath;
+	return isDirectorySync(pathToCheck, fsImplementation) ? getDirectoryGlob({directoryPath, files, extensions}) : directoryPath;
 });
 
 const toPatternsArray = patterns => {
@@ -93,20 +122,19 @@ const toPatternsArray = patterns => {
 	return patterns;
 };
 
-const checkCwdOption = cwd => {
-	if (!cwd) {
+const checkCwdOption = (cwd, fsImplementation = fs) => {
+	if (!cwd || !fsImplementation.statSync) {
 		return;
 	}
 
-	let stat;
 	try {
-		stat = fs.statSync(cwd);
-	} catch {
-		return;
-	}
-
-	if (!stat.isDirectory()) {
-		throw new Error('The `cwd` option must be a path to a directory');
+		if (!fsImplementation.statSync(cwd).isDirectory()) {
+			throw new Error('The `cwd` option must be a path to a directory');
+		}
+	} catch (error) {
+		if (error.message === 'The `cwd` option must be a path to a directory') {
+			throw error;
+		}
 	}
 };
 
@@ -118,7 +146,7 @@ const normalizeOptions = (options = {}) => {
 		cwd: toPath(options.cwd),
 	};
 
-	checkCwdOption(options.cwd);
+	checkCwdOption(options.cwd, options.fs);
 
 	return options;
 };
@@ -284,13 +312,16 @@ const normalizeExpandDirectoriesOption = (options, cwd) => ({
 const generateTasks = async (patterns, options) => {
 	const globTasks = convertNegativePatterns(patterns, options);
 
-	const {cwd, expandDirectories} = options;
+	const {cwd, expandDirectories, fs: fsImplementation} = options;
 
 	if (!expandDirectories) {
 		return globTasks;
 	}
 
-	const directoryToGlobOptions = normalizeExpandDirectoriesOption(expandDirectories, cwd);
+	const directoryToGlobOptions = {
+		...normalizeExpandDirectoriesOption(expandDirectories, cwd),
+		fs: fsImplementation,
+	};
 
 	return Promise.all(globTasks.map(async task => {
 		let {patterns, options} = task;
@@ -300,7 +331,7 @@ const generateTasks = async (patterns, options) => {
 			options.ignore,
 		] = await Promise.all([
 			directoryToGlob(patterns, directoryToGlobOptions),
-			directoryToGlob(options.ignore, {cwd}),
+			directoryToGlob(options.ignore, {cwd, fs: fsImplementation}),
 		]);
 
 		return {patterns, options};
@@ -309,18 +340,21 @@ const generateTasks = async (patterns, options) => {
 
 const generateTasksSync = (patterns, options) => {
 	const globTasks = convertNegativePatterns(patterns, options);
-	const {cwd, expandDirectories} = options;
+	const {cwd, expandDirectories, fs: fsImplementation} = options;
 
 	if (!expandDirectories) {
 		return globTasks;
 	}
 
-	const directoryToGlobSyncOptions = normalizeExpandDirectoriesOption(expandDirectories, cwd);
+	const directoryToGlobSyncOptions = {
+		...normalizeExpandDirectoriesOption(expandDirectories, cwd),
+		fs: fsImplementation,
+	};
 
 	return globTasks.map(task => {
 		let {patterns, options} = task;
 		patterns = directoryToGlobSync(patterns, directoryToGlobSyncOptions);
-		options.ignore = directoryToGlobSync(options.ignore, {cwd});
+		options.ignore = directoryToGlobSync(options.ignore, {cwd, fs: fsImplementation});
 		return {patterns, options};
 	});
 };

package.json

@@ -66,7 +66,6 @@
 		"@sindresorhus/merge-streams": "^4.0.0",
 		"fast-glob": "^3.3.3",
 		"ignore": "^7.0.5",
-		"path-type": "^6.0.0",
 		"slash": "^5.1.0",
 		"unicorn-magic": "^0.3.0"
 	},

readme.md

@@ -101,6 +101,15 @@ This is a more generic form of the `gitignore` option, allowing you to find igno
 
 **Performance tip:** Using a specific path like `'.gitignore'` is much faster than recursive patterns.
 
+##### fs
+
+Type: [`FileSystemAdapter`](https://github.com/mrmlnc/fast-glob#fs)\
+Default: `undefined`
+
+Custom file system implementation (useful for testing or virtual file systems).
+
+**Note:** When using `gitignore` or `ignoreFiles`, the custom fs must also provide `readFile`/`readFileSync` methods.
+
 ### globbySync(patterns, options?)
 
 Returns `string[]` of matching paths.
@@ -221,6 +230,15 @@ Default: `false`
 
 Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.
 
+##### fs
+
+Type: [`FileSystemAdapter`](https://github.com/mrmlnc/fast-glob#fs)\
+Default: `undefined`
+
+Custom file system implementation (useful for testing or virtual file systems).
+
+**Note:** The custom fs must provide `readFile`/`readFileSync` methods for reading `.gitignore` files.
+
 ```js
 import {isGitIgnored} from 'globby';
 

tests/globby.js

@@ -14,6 +14,7 @@ import {
 import {normalizeDirectoryPatternForFastGlob} from '../utilities.js';
 import {
 	PROJECT_ROOT,
+	createContextAwareFs,
 	getPathValues,
 	invalidPatterns,
 	isUnique,
@@ -302,6 +303,12 @@ test('expandDirectories option', async t => {
 	}), ['tmp/a.tmp', 'tmp/b.tmp', 'tmp/c.tmp', 'tmp/d.tmp', 'tmp/e.tmp']);
 });
 
+test('fs option preserves context during directory expansion', async t => {
+	const fsImplementation = createContextAwareFs();
+	const result = await runGlobby(t, temporary, {fs: fsImplementation});
+	t.deepEqual(result, ['tmp/a.tmp', 'tmp/b.tmp', 'tmp/c.tmp', 'tmp/d.tmp', 'tmp/e.tmp']);
+});
+
 test('expandDirectories:true and onlyFiles:true option', async t => {
 	t.deepEqual(await runGlobby(t, temporary, {onlyFiles: true}), ['tmp/a.tmp', 'tmp/b.tmp', 'tmp/c.tmp', 'tmp/d.tmp', 'tmp/e.tmp']);
 });