Add support for path matcher function

index.js

@@ -8,17 +8,18 @@ module.exports = (filename, opts = {}) => {
 
 	const filenames = [].concat(filename);
 
-	return new Promise(resolve => {
+	return new Promise((resolve, reject) => {
 		(function find(dir) {
-			locatePath(filenames, {cwd: dir}).then(file => {
+			const locating = typeof filename === 'function' ? Promise.resolve(filename(dir)) : locatePath(filenames, {cwd: dir});
+			locating.then(file => {
 				if (file) {
-					resolve(path.join(dir, file));
+					resolve(path.resolve(dir, file));
 				} else if (dir === root) {
 					resolve(null);
 				} else {
 					find(path.dirname(dir));
 				}
-			});
+			}).catch(reject);
 		})(startDir);
 	});
 };
@@ -31,10 +32,10 @@ module.exports.sync = (filename, opts = {}) => {
 
 	// eslint-disable-next-line no-constant-condition
 	while (true) {
-		const file = locatePath.sync(filenames, {cwd: dir});
+		const file = typeof filename === 'function' ? filename(dir) : locatePath.sync(filenames, {cwd: dir});
 
 		if (file) {
-			return path.join(dir, file);
+			return path.resolve(dir, file);
 		}
 
 		if (dir === root) {

package.json

@@ -44,6 +44,8 @@
 	},
 	"devDependencies": {
 		"ava": "*",
+		"is-path-inside": "^2.0.0",
+		"pify": "^4.0.0",
 		"tempy": "^0.2.1",
 		"xo": "*"
 	}

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,27 @@ 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(filename, [options])
+### findUp(matcher, [options])
 
 Returns a `Promise` for either the filepath or `null` if it couldn't be found.
 
@@ -62,19 +78,28 @@ Returns a `Promise` for either the filepath or `null` if it couldn't be found.
 Returns a `Promise` for either the first filepath found (by respecting the order) or `null` if none could be found.
 
 ### findUp.sync(filename, [options])
+### findUp.sync(matcher, [options])
 
 Returns a filepath or `null`.
 
 ### findUp.sync([filenameA, filenameB], [options])
 
-Returns the first filepath found (by respecting the order) or `null`.
+Returns the first filepath found (by respecting the order) or `null` if none could be found.
 
 #### filename
 
 Type: `string`
 
 Filename of the file 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 m from '.';
 
@@ -244,3 +246,134 @@ test('sync (not found, custom cwd)', t => {
 
 	t.is(filePath, null);
 });
+
+test('async (matcher function)', async t => {
+	const cwd = process.cwd();
+
+	t.is(await m(dir => {
+		t.is(dir, cwd);
+		return dir;
+	}), cwd);
+
+	t.is(await m(() => {
+		return '.';
+	}), cwd);
+
+	t.is(await m(async () => {
+		return 'foo.txt';
+	}), path.join(cwd, 'foo.txt'));
+
+	t.is(await m(() => {
+		return '..';
+	}), path.join(cwd, '..'));
+
+	t.is(await m(dir => {
+		return (dir !== cwd) && dir;
+	}), path.join(cwd, '..'));
+
+	t.is(await m(dir => {
+		return (dir !== 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 m(async dir => {
+		t.is(typeof dir, 'string');
+		const stat = await pify(fs.stat)(dir);
+		t.true(stat.isDirectory());
+		t.true((dir === cwd) || isPathInside(cwd, dir));
+		t.false(visited.has(dir));
+		visited.add(dir);
+	}), null);
+	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(m(dir => {
+		visited.add(dir);
+		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(m(async dir => {
+		visited.add(dir);
+		throw new Error('Some async rejection');
+	}), {
+		message: 'Some async rejection'
+	});
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});
+
+test('sync (matcher function)', t => {
+	const cwd = process.cwd();
+
+	t.is(m.sync(dir => {
+		t.is(dir, cwd);
+		return dir;
+	}), cwd);
+
+	t.is(m.sync(() => {
+		return '.';
+	}), cwd);
+
+	t.is(m.sync(() => {
+		return 'foo.txt';
+	}), path.join(cwd, 'foo.txt'));
+
+	t.is(m.sync(() => {
+		return '..';
+	}), path.join(cwd, '..'));
+
+	t.is(m.sync(dir => {
+		return (dir !== cwd) && dir;
+	}), path.join(cwd, '..'));
+
+	t.is(m.sync(dir => {
+		return (dir !== 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(m.sync(dir => {
+		t.is(typeof dir, 'string');
+		const stat = fs.statSync(dir);
+		t.true(stat.isDirectory());
+		t.true((dir === cwd) || isPathInside(cwd, dir));
+		t.false(visited.has(dir));
+		visited.add(dir);
+	}), null);
+	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(() => {
+		m.sync(dir => {
+			visited.add(dir);
+			throw new Error('Some problem');
+		});
+	}, {
+		message: 'Some problem'
+	});
+	t.true(visited.has(cwd));
+	t.is(visited.size, 1);
+});