Registry / data / vfile-find-down

vfile-find-down

JSON →
library7.1.0jsnpmunverified

vfile-find-down is a utility for the vfile ecosystem, designed to locate one or multiple files by recursively searching the file system downwards from a given path. It processes files into `VFile` objects but does not populate their content, suggesting the use of `to-vfile` for actual file reading. Currently at version 7.1.0, the package maintains an active release cadence, with major versions introducing significant changes like the move to ESM and stricter Node.js requirements. It serves as a complementary tool to `vfile-find-up`, which handles upward directory traversal, making it suitable for scenarios like finding all Markdown files within a project directory rather than configuration files in parent directories.

npm install vfile-find-down
INSTALL
IMPORT
SIG · VFILE-FIND-DOWN
V
vfile-find-down
datajavascriptv7.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

findDown
import { findDown } from 'vfile-find-down'
const findDown = require('vfile-find-down')
'vfile-find-down' has been an ESM-only package since v6.0.0, requiring Node.js 16+ since v7.0.0. CommonJS 'require' will not work for direct imports.
findDownAll
import { findDownAll } from 'vfile-find-down'
const findDownAll = require('vfile-find-down').findDownAll
The `findDownAll` function was named `findDown` in versions prior to v7.0.0. This package is ESM-only since v6.0.0.
Test
import type { Test } from 'vfile-find-down'
import { Test } from 'vfile-find-down'
'Test' is a TypeScript type definition and should be imported using 'import type' for type-only imports, especially in environments configured for isolated modules.

Demonstrates how to use `findDown` to locate the first Markdown file in the current directory or its subdirectories and how to optionally read its content using `to-vfile`.

import { findDown } from 'vfile-find-down' import { toVFile } from 'to-vfile' import path from 'node:path' import process from 'node:process' async function run() { const rootDir = process.cwd(); // Assuming there's a readme.md in the current or a sub-directory for this example // To make it runnable, ensure a '.md' file exists in the current directory or a subdirectory. // For testing purposes, you might create a temporary file: // await fs.promises.writeFile(path.join(rootDir, 'temp.md'), '# Hello'); // Find the first markdown file downwards from the current directory. const firstMdFile = await findDown('.md', rootDir); if (firstMdFile) { console.log('Found first Markdown file:', firstMdFile.history[0]); // To read its content, use toVFile (optional dependency) const fileWithContent = await toVFile.read(firstMdFile.history[0]); console.log('Content of the file (first 50 chars):', fileWithContent.value?.toString().substring(0, 50)); } else { console.log('No Markdown files found.'); } // Example for finding all markdown files const allMdFiles = await findDown('.md', rootDir); if (Array.isArray(allMdFiles) && allMdFiles.length > 0) { console.log('\nAll Markdown files found:'); allMdFiles.forEach(file => console.log(file.history[0])); } } run().catch(console.error);
Debug
Known issues
breakingVersion 7.0.0 changed the minimum Node.js requirement to Node.js 16.
fix
Ensure your Node.js environment is version 16 or higher. Update Node.js if necessary.
affects: >=7.0.0
breakingVersion 6.0.0 converted `vfile-find-down` to an ES module (ESM-only), deprecating CommonJS `require()`.
fix
Migrate your import statements from `const pkg = require('pkg')` to `import { pkg } from 'pkg'`.
affects: >=6.0.0
breakingVersion 7.0.0 renamed the API functions: `findDownOne` was renamed to `findDown`, and `findDown` was renamed to `findDownAll`.
fix
Update your code to use the new function names: `findDown` for finding the first file, and `findDownAll` for finding all files.
affects: >=7.0.0
breakingVersion 7.0.0 changed the callback return value from bitwise symbols (e.g., `CONTINUE | BREAK`) to a plain result object with `break`, `include`, `skip` boolean fields.
fix
If you are using the callback API, update your logic to expect and return an object like `{ break: true, include: true }` instead of symbol combinations.
affects: >=7.0.0
breakingVersion 7.0.0 changed to use an `export` map, which means accessing undocumented or private internal APIs may no longer work.
fix
Avoid using undocumented or private APIs. Only use the officially exported identifiers like `findDown` and `findDownAll`.
affects: >=7.0.0
gotchaThe `vfile-find-down` utility only locates files and populates `VFile` objects with path information; it does not read file contents into the `file.value` property by default.
fix
If you need to access the file's content, use `to-vfile` (e.g., `toVFile.read(vfile)`) after finding the `VFile`.
affects: all
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-find-down/index.js from ... not supported.
Attempting to import `vfile-find-down` using CommonJS `require()` syntax in a Node.js environment, but the package is ESM-only since v6.0.0.
fix
Update your import statement to use ES module syntax: `import { findDown } from 'vfile-find-down';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
TypeError: (0, vfile_find_down_1.findDown) is not a function
This error often occurs after upgrading to v7.0.0 if you were previously using `findDown` to find all files. The `findDown` function was renamed to `findDownAll`, and `findDownOne` was renamed to `findDown`.
fix
If you intended to find all files, change your call to `findDownAll`. If you intended to find a single file and were using `findDownOne`, you can now use `findDown`.
TypeError: Path must be a string. Received undefined
The `paths` argument for `findDown` or `findDownAll` was not provided or was `undefined`. This often happens when the second argument to `findDown` (which is `paths`) is missing or invalid.
fix
Ensure you pass a valid string or array of strings (or `URL` objects) as the `paths` argument, specifying where to start the search. By default, it uses `process.cwd()` if omitted, but explicit undefined might cause issues.
Upgrade
Version history
7.1.0latest on npm
Audit
Dependencies
vfilerequiredCore data structure for representing files and messages, integral to the vfile ecosystem as this utility returns `VFile` objects.
to-vfileoptionalCommonly used to read file contents into the VFile `value` property, as `vfile-find-down` only locates files without reading their contents.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
vfile-find-down — npm install vfile-find-down · libregistry