Vfile-find-down NPM

vfile-find-down

vfile utility to find files by searching the file system downwards.

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). use to-vfile for that.

Signatures

(test[, paths], callback) => undefined
(test[, paths]) => Promise<VFile>

Parameters

test (Test) — things to search for
paths (Array<URL | string> | URL | string, default: process.cwd()) — places to search from
callback (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). use to-vfile for that.

Signatures

(test[, paths], callback) => undefined
(test[, paths]) => Promise<Array<VFile>>

Parameters

test (Test) — things to search for
paths (Array<URL | string> | URL | string, default: process.cwd()) — places to search from
callback (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

file (VFile) — file to handle
stats (Stats) — stats from fs.stat

Returns

How to handle this file (Result, optional).

`Callback`

Callback called when done finding one file (TypeScript type).

Parameters

error (Error or undefined) — error; errors are currently never passed
file (VFile or undefined) — file

Returns

Nothing (undefined).

`CallbackAll`

Callback called when done (TypeScript type).

Parameters

error (Error or undefined) — error; errors are currently never passed
files (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 folder
include (boolean, default: false) — include this file or folder
skip (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.