vfile-find-down
vfile utility to find files by searching the file system downwards.
Contents
What is this?
This utility lets you find one or many files downwards.
When should I use this?
You can use this utility if you want to find files in, say, a folder. One example is all markdown files. If you instead want to find files upwards, such as config files, you can use vfile-find-up
.
Install
This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:
npm install vfile-find-down
Use
import {findDown} from 'vfile-find-down'
console.log(await findDown('.md'))
Yields:
[ VFile {
data: {},
messages: [],
history: [ '/Users/tilde/projects/oss/vfile-find-down/readme.md' ],
cwd: '/Users/tilde/projects/oss/vfile-find-down' } ]
API
This package exports the identifiers findDown
, findDownOne
, INCLUDE
, SKIP
, and BREAK
. There is no default export.
findDown(tests[, paths][, callback])
Search for tests
downwards. Calls callback with either an error or an array of files passing tests
, or returns them as a promise if no callback
is passed.
👉 Note: files are not read (their
value
is not populated).
Signatures
(tests: Tests, paths?: string|Array<string>, callback: Callback): void
(tests: Tests, paths?: string|Array<string>): Promise<Array<VFile>>
Parameters
tests
Things to search for (string|Function|Array<Tests>
).
If an array is passed in, any test must match a given file for it to be included.
If a string
is passed in, the basename
or extname
of files must match it for them to be included (and hidden directories and node_modules
will not be searched).
Otherwise, they must be Assert
.
paths
Place or places to search from (Array<string>
or string
, default: process.cwd()
).
callback
Function called with all matching files (function cb(error[, files])
).
findDownOne(tests[, paths][, callback])
Like findDown
, but either calls callback
with the first found file or null
, or returns a promise that resolved to a file or null
.
function assert(file, stats)
Check whether a file should be included. Called with a vfile and a stats object.
Returns
true
orINCLUDE
— include the file in the resultsSKIP
— do not search inside this directoryBREAK
— stop searching for files- anything else is ignored: files are neither included nor skipped
The different flags can be combined by using the pipe operator: INCLUDE | SKIP
.
Types
This package is fully typed with TypeScript. It exports the additional types Assert
and Test
.
Compatibility
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.
Contribute
See contributing.md
in vfile/.github
for ways to get started. See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.