vfile-find-up

Find one or more files (exposed as VFiles) by searching the file system upwards.

Installation

npm:

npm install vfile-find-up

Usage

Require dependencies:

var findUp = require('vfile-find-up');

Search for files named package.json from the current working directory upwards:

findUp.all('package.json', console.log);
/* null [ VFile {
 *     contents: '',
 *     messages: [],
 *     history: [ '/Users/foo/bar/baz/package.json' ],
 *     directory: '/Users/foo/bar/baz',
 *     filename: 'package',
 *     extension: 'json' },
 *   VFile {
 *     contents: '',
 *     messages: [],
 *     history: [ '/Users/foo/package.json' ],
 *     directory: '/Users/foo',
 *     filename: 'package',
 *     extension: 'json' } ]
 */

Search for the first file:

findUp.one('package.json', console.log);
/* null VFile {
 *   contents: '',
 *   messages: [],
 *   history: [ '/Users/foo/bar/baz/package.json' ],
 *   directory: '/Users/foo/bar/baz',
 *   filename: 'package',
 *   extension: 'json' }
 */

findUp.one(test[, directory], callback)

Find a file or a directory upwards.

Example

findUp.one('package.json', console.log);
/* null VFile {
 *   contents: '',
 *   messages: [],
 *   history: [ '/Users/foo/bar/baz/package.json' ],
 *   directory: '/Users/foo/bar/baz',
 *   filename: 'package',
 *   extension: 'json' }
 */

Signatures

• findUp.one(filePath[, directory], callback);
• findUp.one(extension[, directory], callback);
• findUp.one(test[, directory], callback);
• findUp.one(tests[, directory], callback).

Parameters

• filePath (string) — Filename (including extension) to search for;

• extension (string) — File extension to search for (must start with a .);

• test (Function) — Function invoked to check whether a virtual file should be included;

• tests (Array.<Function|filePath|extension>) — List of tests, any of which should match a given file for it to be included.

• directory (string, optional, default: process.cwd()) — Place to start searching from;

• callback (Function); — Function invoked when a matching file or the top of the volume is reached.

Notes

• Virtual Files are not read (their content is not populated).

function callback(err, file)

Invoked when a matching file or the top of the volume is reached.

Parameters

• err (Error, optional);
• file (VFile, optional).

Notes

• The err parameter is never populated.

findUp.all(test[, directory], callback)

Find files or directories upwards.

Example

findUp.all('package.json', console.log);
/* null [ VFile {
 *     contents: '',
 *     messages: [],
 *     history: [ '/Users/foo/bar/baz/package.json' ],
 *     directory: '/Users/foo/bar/baz',
 *     filename: 'package',
 *     extension: 'json' },
 *   VFile {
 *     contents: '',
 *     messages: [],
 *     history: [ '/Users/foo/package.json' ],
 *     directory: '/Users/foo',
 *     filename: 'package',
 *     extension: 'json' } ]
 */

Signatures

• findUp.all(filePath[, directory], callback);
• findUp.all(extension[, directory], callback);
• findUp.all(test[, directory], callback);
• findUp.all(tests[, directory], callback).

Parameters

• filePath (string) — Filename (including extension) to search for;

• extension (string) — File extension to search for (must start with a .);

• test (Function) — Function invoked to check whether a virtual file should be included;

• tests (Array.<Function|filePath|extension>) — List of tests, any of which should match a given file for it to be included.

• directory (string, optional, default: process.cwd()) — Place to start searching from;

• callback (Function); — Function invoked when matching files or the top of the volume is reached.

Notes

• Virtual Files are not read (their content is not populated).

function callback(err, files)

Invoked when files or the top of the volume is reached.

Parameters

• err (Error, optional);
• files (Array.<VFile>, optional).

Notes

• The err parameter is never populated.

function test(file)

Check whether a virtual file should be included.

Parameters

• file (VFile).

Returns:

• boolean — When truthy, the file is included;

• number — Bitmask (findUp.INCLUDE and findUp.EXIT) to control searching behavior.

findUp.INCLUDE

Flag used as an alternative to returning true from test, ensuring the tested file is included and passed to callback.

findUp.EXIT

Flag used to stop searching for files returned to test.

License

MIT © Titus Wormer