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 14.14+ and 16.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 BREAK
, INCLUDE
, SKIP
, findDown
, and findDownOne
. There is no default export.
findDown(test[, paths][, callback])
Find files or folders downwards.
👉 Note: files are not read (their
value
is not populated).
Signatures
(test[, paths], callback) => void
(test[, paths]) => Promise<Array<VFile>>
Parameters
test
(Test
) — things to search forpaths
(Array<string> | string
, default:process.cwd()
) — places to search fromcallback
(Callback
, optional) — callback called when done
Returns
Nothing when callback
is given (void
), otherwise a promise that resolves to files (Array<VFile>
).
findDownOne(test[, paths][, callback])
Find the first file or folder downwards.
👉 Note: files are not read (their
value
is not populated).
Signatures
(test[, paths], callback) => void
(test[, paths]) => Promise<VFile>
Parameters
test
(Test
) — things to search forpaths
(Array<string> | string
, default:process.cwd()
) — places to search fromcallback
(CallbackOne
, optional) — callback called when done
Returns
Nothing when callback
is given (void
), otherwise a promise that resolves to a file (VFile | null
).
BREAK
Stop searching (number
).
INCLUDE
Include this file (number
).
SKIP
Skip this folder (number
).
Assert
Handle a file (TypeScript type).
Parameters
Returns
How to handle this file (boolean | number
, optional).
Booleans are treated as INCLUDE
(when true
) or SKIP
(when false
). No result is treated as SKIP
. The different flags can be combined by using the pipe operator: INCLUDE | SKIP
.
Callback
Callback called when done (TypeScript type).
Parameters
error
(Error | null
) — error; errors are currently never passedfiles
(Array<VFile>
) — files
Returns
Nothing (void
).
CallbackOne
Callback called when done finding one file (TypeScript type).
Parameters
error
(Error | null
) — error; errors are currently never passedfile
(VFile | null
) — file
Returns
Nothing (void
).
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
, CallbackOne
, 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 14.14+ and 16.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.