vfile-find-down

vfile utility to find one or more files by searching the file system downwards

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
vfile-find-down
7.1.05 months ago8 years agoMinified + gzip package size for vfile-find-down in KB

Popular Searches

Readme

vfile-find-down
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
vfile utility to find files by searching the file system downwards.

Contents

*   [`findDown(test[, paths][, callback])`](#finddowntest-paths-callback)
*   [`findDownAll(test[, paths][, callback])`](#finddownalltest-paths-callback)
*   [`Assert`](#assert)
*   [`Callback`](#callback)
*   [`CallbackAll`](#callbackall)
*   [`Result`](#result)
*   [`Test`](#test)

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-upvfile-find-up.

Install

This package is ESM onlyesm. 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 findDownapi-find-down and findDownAllapi-find-down-all. 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-vfileto-vfile for that.
Signatures
  • (test[, paths], callback) => undefined
  • (test[, paths]) => Promise<VFile>
Parameters
— things to search for
  • paths (Array<URL | string> | URL | string, default: process.cwd())
— places to search from
— callback called when done
Returns
Nothing when callback is given (undefined), otherwise a promise that resolves to a file (VFilevfile or undefined).

findDownAll(test[, paths][, callback])

Find files or folders downwards.
👉 Note: files are not read (their value is not populated). use to-vfileto-vfile for that.
Signatures
  • (test[, paths], callback) => undefined
  • (test[, paths]) => Promise<Array<VFile>>
Parameters
— things to search for
  • paths (Array<URL | string> | URL | string, default: process.cwd())
— places to search from
— callback called when done
Returns
Nothing when callback is given (undefined), otherwise a promise that resolves to files (Array<VFile>vfile).

Assert

Handle a file (TypeScript type).
Parameters
— file to handle
— stats from `fs.stat`
Returns
How to handle this file (Resultapi-result, optional).

Callback

Callback called when done finding one file (TypeScript type).
Parameters
  • error (Error or undefined)
— error; errors are currently never passed
— file
Returns
Nothing (undefined).

CallbackAll

Callback called when done (TypeScript type).
Parameters
  • error (Error or undefined)
— error; errors are currently never passed
— 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 Assertapi-assert, Callbackapi-callback, CallbackAllapi-callback-all, Resultapi-result, and Testapi-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.mdcontributing in vfile/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor