vfile-find-down
v7.1.0
Published
vfile utility to find one or more files by searching the file system downwards
Downloads
19,907
Maintainers
Readme
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 16), install with npm:
npm install vfile-find-down
Use
import {findDown} from 'vfile-find-down'
console.log(await findDown('.md'))
Yields:
VFile {
cwd: '/Users/tilde/Projects/oss/vfile-find-down',
data: {},
history: [ '/Users/tilde/Projects/oss/vfile-find-down/readme.md' ],
messages: []
}
API
This package exports the identifiers
findDown
and
findDownAll
.
There is no default export.
findDown(test[, paths][, callback])
Find the first file or folder downwards.
👉 Note: files are not read (their
value
is not populated). useto-vfile
for that.
Signatures
(test[, paths], callback) => undefined
(test[, paths]) => Promise<VFile>
Parameters
test
(Test
) — things to search forpaths
(Array<URL | string> | URL | string
, default:process.cwd()
) — places to search fromcallback
(Callback
, optional) — callback called when done
Returns
Nothing when callback
is given (undefined
), otherwise a promise that
resolves to a file (VFile
or undefined
).
findDownAll(test[, paths][, callback])
Find files or folders downwards.
👉 Note: files are not read (their
value
is not populated). useto-vfile
for that.
Signatures
(test[, paths], callback) => undefined
(test[, paths]) => Promise<Array<VFile>>
Parameters
test
(Test
) — things to search forpaths
(Array<URL | string> | URL | string
, default:process.cwd()
) — places to search fromcallback
(CallbackAll
, optional) — callback called when done
Returns
Nothing when callback
is given (undefined
), otherwise a promise that
resolves to files (Array<VFile>
).
Assert
Handle a file (TypeScript type).
Parameters
Returns
How to handle this file (Result
, optional).
Callback
Callback called when done finding one file (TypeScript type).
Parameters
error
(Error
orundefined
) — error; errors are currently never passedfile
(VFile
orundefined
) — file
Returns
Nothing (undefined
).
CallbackAll
Callback called when done (TypeScript type).
Parameters
error
(Error
orundefined
) — error; errors are currently never passedfiles
(Array<VFile>
) — files
Returns
Nothing (undefined
).
Result
What to do when collecting a file or folder (TypeScript type).
Fields
break
(boolean
, default:false
) — stop searching after this file or folderinclude
(boolean
, default:false
) — include this file or folderskip
(boolean
, default:false
) — do not search inside this folder
Test
Things to search for (TypeScript type).
For strings, the basename
or extname
of files must match them and
hidden folders and node_modules
will not be searched.
For arrays, any test in them must match.
Type
type Test = Array<Assert | string> | Assert | string
Types
This package is fully typed with TypeScript.
It exports the additional types
Assert
,
Callback
,
CallbackAll
,
Result
, and
Test
.
Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, vfile-find-down@^7
,
compatible with Node.js 16.
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.