filehound

Filehound

Flexible and fluent interface for searching the file system

Installation

npm install --save filehound

Requires Node.js 24 or later.

Upgrading from V1? See the migration guide.

Usage

The example below prints all of the files in a directory that have the .json file extension:

import { FileHound, ext } from 'filehound';

const files = await FileHound.create()
  .paths('/some/dir')
  .match(ext('json'))
  .find();

console.log(files);

Iterating over matches

find() waits for the whole search to finish. To handle each match as it's found, loop over iterate() instead. Matches come in the same order as find(), and the search only runs a little ahead of the loop, so a large search doesn't hold every match in memory:

import { FileHound, ext } from 'filehound';

const query = FileHound.create()
  .paths('/some/dir')
  .match(ext('json'));

for await (const file of query.iterate()) {
  console.log(file);
}

Leaving the loop early stops the search, for example to find the first match only:

for await (const file of query.iterate()) {
  console.log(`First match: ${file}`);
  break;
}

Documentation

For more examples and API details, see API documentation

Runnable examples are in the examples directory. Each one searches the current directory, for example node by-extension.mts.

Test

npm test

To generate a test coverage report:

npm run coverage

Contributing

See contributing guide

Related modules

• Finding files by content - FileSniffer