Add support for path matcher function

index.js

@@ -2,18 +2,23 @@
 const path = require('path');
 const locatePath = require('locate-path');
 
+const stop = Symbol('findUp.stop');
+
 module.exports = async (name, options = {}) => {
 	let directory = path.resolve(options.cwd || '');
 	const {root} = path.parse(directory);
 	const paths = [].concat(name);
-
 	// eslint-disable-next-line no-constant-condition
 	while (true) {
 		// eslint-disable-next-line no-await-in-loop
-		const foundPath = await locatePath(paths, {cwd: directory});
+		const foundPath = await (typeof name === 'function' ? name(directory) : locatePath(paths, {cwd: directory}));
+
+		if (foundPath === stop) {
+			return;
+		}
 
 		if (foundPath) {
-			return path.join(directory, foundPath);
+			return path.resolve(directory, foundPath);
 		}
 
 		if (directory === root) {
@@ -31,10 +36,14 @@ module.exports.sync = (name, options = {}) => {
 
 	// eslint-disable-next-line no-constant-condition
 	while (true) {
-		const foundPath = locatePath.sync(paths, {cwd: directory});
+		const foundPath = typeof name === 'function' ? name(directory) : locatePath.sync(paths, {cwd: directory});
+
+		if (foundPath === stop) {
+			return;
+		}
 
 		if (foundPath) {
-			return path.join(directory, foundPath);
+			return path.resolve(directory, foundPath);
 		}
 
 		if (directory === root) {
@@ -44,3 +53,5 @@ module.exports.sync = (name, options = {}) => {
 		directory = path.dirname(directory);
 	}
 };
+
+module.exports.stop = stop;

package.json

@@ -44,6 +44,8 @@
 	},
 	"devDependencies": {
 		"ava": "^1.4.1",
+		"is-path-inside": "^2.1.0",
+		"pify": "^4.0.1",
 		"tempy": "^0.3.0",
 		"tsd": "^0.7.2",
 		"xo": "^0.24.0"

readme.md

@@ -39,6 +39,8 @@ $ npm install find-up
 `example.js`
 
 ```js
+const fs = require('fs');
+const path = require('path');
 const findUp = require('find-up');
 
 (async () => {
@@ -47,13 +49,28 @@ const findUp = require('find-up');
 
 	console.log(await findUp(['rainbow.png', 'unicorn.png']));
 	//=> '/Users/sindresorhus/unicorn.png'
+
+	console.log(await findUp(dir => {
+		return fs.existsSync(path.join(dir, 'unicorn.png')) && 'foo';
+	}));
+	//=> '/Users/sindresorhus/foo'
+
+	console.log(await findUp(async dir => {
+		const children = await fs.promises.readdir(dir);
+		if (children.some(fileName => fileName.endsWith('.png'))) {
+			return dir;
+		}
+	}));
+	//=> '/Users/sindresorhus'
 })();
 ```
 
 
 ## API
 
+
 ### findUp(name, [options])
+### findUp(matcher, [options])
 
 Returns a `Promise` for either the path or `undefined` if it couldn't be found.
 
@@ -62,6 +79,7 @@ Returns a `Promise` for either the path or `undefined` if it couldn't be found.
 Returns a `Promise` for either the first path found (by respecting the order) or `undefined` if none could be found.
 
 ### findUp.sync(name, [options])
+### findUp.sync(matcher, [options])
 
 Returns a path or `undefined` if it couldn't be found.
 
@@ -75,6 +93,14 @@ Type: `string`
 
 Name of the file or directory to find.
 
+#### matcher
+
+Type: `Function`
+
+A function that will be called with each directory until it returns a filepath to stop the search or the root directory has been reached and nothing was found. Useful if you want to match files with a certain pattern, set of permissions, or other advanced use cases.
+
+When using async mode, `matcher` may optionally be an `async` function or return a `Promise` for the filepath.
+
 #### options
 
 Type: `object`

test.js

@@ -1,6 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import test from 'ava';
+import isPathInside from 'is-path-inside';
+import pify from 'pify';
 import tempy from 'tempy';
 import findUp from '.';
 
@@ -54,13 +56,13 @@ test('sync (child file)', t => {
 	t.is(foundPath, absolute.packageJson);
 });
 
-test('async (child dir)', async t => {
+test('async (child directory)', async t => {
 	const foundPath = await findUp(name.fixtureDirectory);
 
 	t.is(foundPath, absolute.fixtureDirectory);
 });
 
-test('sync (child dir)', t => {
+test('sync (child directory)', t => {
 	const foundPath = findUp.sync(name.fixtureDirectory);
 
 	t.is(foundPath, absolute.fixtureDirectory);
@@ -174,43 +176,43 @@ test('sync (nested descendant file)', t => {
 	t.is(foundPath, absolute.baz);
 });
 
-test('async (nested descendant dir)', async t => {
+test('async (nested descendant directory)', async t => {
 	const foundPath = await findUp(relative.barDir);
 
 	t.is(foundPath, absolute.barDir);
 });
 
-test('sync (nested descendant dir)', t => {
+test('sync (nested descendant directory)', t => {
 	const foundPath = findUp.sync(relative.barDir);
 
 	t.is(foundPath, absolute.barDir);
 });
 
-test('async (nested cousin dir, custom cwd)', async t => {
+test('async (nested cousin directory, custom cwd)', async t => {
 	const foundPath = await findUp(relative.barDir, {
 		cwd: relative.fixtureDirectory
 	});
 
 	t.is(foundPath, absolute.barDir);
 });
 
-test('sync (nested cousin dir, custom cwd)', t => {
+test('sync (nested cousin directory, custom cwd)', t => {
 	const foundPath = findUp.sync(relative.barDir, {
 		cwd: relative.fixtureDirectory
 	});
 
 	t.is(foundPath, absolute.barDir);
 });
 
-test('async (ancestor dir, custom cwd)', async t => {
+test('async (ancestor directory, custom cwd)', async t => {
 	const foundPath = await findUp(name.fixtureDirectory, {
 		cwd: relative.barDir
 	});
 
 	t.is(foundPath, absolute.fixtureDirectory);
 });
 
-test('sync (ancestor dir, custom cwd)', t => {
+test('sync (ancestor directory, custom cwd)', t => {
 	const foundPath = findUp.sync(name.fixtureDirectory, {
 		cwd: relative.barDir
 	});
@@ -247,3 +249,156 @@ test('sync (not found, custom cwd)', t => {
 
 	t.is(foundPath, undefined);
 });
+
+test('async (matcher function)', async t => {
+	const cwd = process.cwd();
+
+	t.is(await findUp(directory => {
+		t.is(directory, cwd);
+		return directory;
+	}), cwd);
+
+	t.is(await findUp(() => {
+		return '.';
+	}), cwd);
+
+	t.is(await findUp(async () => {
+		return 'foo.txt';
+	}), path.join(cwd, 'foo.txt'));
+
+	t.is(await findUp(() => {
+		return '..';
+	}), path.join(cwd, '..'));
+
+	t.is(await findUp(directory => {
+		return (directory !== cwd) && directory;
+	}), path.join(cwd, '..'));
+
+	t.is(await findUp(directory => {
+		return (directory !== cwd) && 'foo.txt';
+	}), path.join(cwd, '..', 'foo.txt'));
+});
+
+test('async (not found, matcher function)', async t => {
+	const cwd = process.cwd();
+	const {root} = path.parse(cwd);
+	const visited = new Set();
+	t.is(await findUp(async directory => {
+		t.is(typeof directory, 'string');
+		const stat = await pify(fs.stat)(directory);
+		t.true(stat.isDirectory());
+		t.true((directory === cwd) || isPathInside(cwd, directory));
+		t.false(visited.has(directory));
+		visited.add(directory);
+	}), undefined);
+	t.true(visited.has(cwd));
+	t.true(visited.has(root));
+});
+
+test('async (matcher function throws)', async t => {
+	const cwd = process.cwd();
+	const visited = new Set();
+	await t.throwsAsync(findUp(directory => {
+		visited.add(directory);
+		throw new Error('Some sync throw');
+	}), {
+		message: 'Some sync throw'
+	});
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});
+
+test('async (matcher function rejects)', async t => {
+	const cwd = process.cwd();
+	const visited = new Set();
+	await t.throwsAsync(findUp(async directory => {
+		visited.add(directory);
+		throw new Error('Some async rejection');
+	}), {
+		message: 'Some async rejection'
+	});
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});
+
+test('async (matcher function stops early)', async t => {
+	const cwd = process.cwd();
+	const visited = new Set();
+	t.is(await findUp(async directory => {
+		visited.add(directory);
+		return findUp.stop;
+	}), undefined);
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});
+
+test('sync (matcher function)', t => {
+	const cwd = process.cwd();
+
+	t.is(findUp.sync(directory => {
+		t.is(directory, cwd);
+		return directory;
+	}), cwd);
+
+	t.is(findUp.sync(() => {
+		return '.';
+	}), cwd);
+
+	t.is(findUp.sync(() => {
+		return 'foo.txt';
+	}), path.join(cwd, 'foo.txt'));
+
+	t.is(findUp.sync(() => {
+		return '..';
+	}), path.join(cwd, '..'));
+
+	t.is(findUp.sync(directory => {
+		return (directory !== cwd) && directory;
+	}), path.join(cwd, '..'));
+
+	t.is(findUp.sync(directory => {
+		return (directory !== cwd) && 'foo.txt';
+	}), path.join(cwd, '..', 'foo.txt'));
+});
+
+test('sync (not found, matcher function)', t => {
+	const cwd = process.cwd();
+	const {root} = path.parse(cwd);
+	const visited = new Set();
+	t.is(findUp.sync(directory => {
+		t.is(typeof directory, 'string');
+		const stat = fs.statSync(directory);
+		t.true(stat.isDirectory());
+		t.true((directory === cwd) || isPathInside(cwd, directory));
+		t.false(visited.has(directory));
+		visited.add(directory);
+	}), undefined);
+	t.true(visited.has(cwd));
+	t.true(visited.has(root));
+});
+
+test('sync (matcher function throws)', t => {
+	const cwd = process.cwd();
+	const visited = new Set();
+	t.throws(() => {
+		findUp.sync(directory => {
+			visited.add(directory);
+			throw new Error('Some problem');
+		});
+	}, {
+		message: 'Some problem'
+	});
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});
+
+test('sync (matcher function stops early)', t => {
+	const cwd = process.cwd();
+	const visited = new Set();
+	t.is(findUp.sync(directory => {
+		visited.add(directory);
+		return findUp.stop;
+	}), undefined);
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});