Filehound

Flexible and fluent interface for searching the file system

• Installation
• Features
• Demo
• Usage
• API
• Instance methods
• Test
• Contributing

Installation

npm install --save filehound

Features

• Flexible search filters
• Simple fluent interface
• Ability to combine search results from multiple queries
• Supports promises and callbacks

Demo

Usage

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

const FileHound = require('filehound');

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

files.then(console.log);

Matching the filename

Find all the files that start with dev:

const files = FileHound.create()
  .paths('/etc/pki/')
  .match('dev*')
  .find();

Filtering by file size

Find all of the files in a directory that are larger than 1024 bytes:

const files = FileHound.create()
  .paths('/some/dir')
  .size('>1024')
  .find();

const files = FileHound.create()
  .paths('/some/dir')
  .size('<=1mb')
  .find();

Combining filters

Find all the .txt files that are larger than 1024 bytes and start with note:

const files = FileHound.create()
  .paths('/etc/pki/')
  .match('note*')
  .ext('txt')
  .size('>1024')
  .find();

Inverse filtering

Find all of the files that don't have the .json extension:

const files = FileHound.create()
  .ext('json')
  .not()
  .find();

Limiting the depth of a recursive search

Find all files but only in the current directory (recursion off):

const files = FileHound.create()
  .depth(0)
  .find();

Combining multiple searches

Find all the files that are either over 1K or have the .json file extension:

const filesOverOneK = FileHound.create()
  .paths('/some/dir')
  .size('>1k')
  .find();

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

const files = FileHound.any(filesOverOneK, jsonFiles);

Using callbacks

Find all empty text files in /tmp:

FileHound.create()
  .paths('/tmp')
  .ext('txt')
  .isEmpty()
  .find((err, emptyTextFiles) => {
    console.log(emptyTextFiles);
  });

API

Static methods

FileHound.create() -> FileHound

Parameters - None

Returns

Returns a FileHound instance.

FileHound.any(FileHound...) -> Promise

Parameters

• Accepts one or more instances of FileHound. Will unpack an array.

Returns

Returns a Promise of all matches. If the Promise fulfills, the fulfillment value is an array of all matching files.

FileHound.not(FileHound...) -> Promise

Parameters

• Accepts one or more instances of FileHound to negate. Will unpack an array.

Returns

• If the Promise fulfills, the fulfillment value is an array of negated matches

Instance methods

.paths(paths...) -> FileHound

Directories to search. Accepts one or more directories or a reference to an array of directories

Parameters

• path - array of directories

Returns

• Returns a FileHound instance

.ext(extension) -> FileHound

Parameters

• extension - file extension to filter by

Returns

• Returns a FileHound instance

.glob(globPattern) -> FileHound

Parameters

• glob - file glob (as string) to filter by

Returns

• Returns a FileHound instance

.match(globPattern) -> FileHound

synonym for .glob

.size(sizeExpression) -> FileHound

Parameters

• sizeExpression - accepts a positive integer representing the file size. File size units are:

  • bytes, specified using b.
  • kilobytes, specified using k or kb,
  • megabytes, specified using m or mb
  • terabytes, specified using t or tb
  • gigabytes, specified using g or gb

  If no unit is specified, bytes is used by default.

  Optionally, expressions can be prefixed with a comparison operator, including:

  • less than using <
  • greater than using >
  • equality using == or =
  • less than or equal to using <=
  • greater than or equal to >=

  Examples:

  • equal to 10 bytes: 10
  • equal to 10 bytes: ==10b
  • less than 10 bytes: <10
  • greater than 50 megabytes: >10mg

Returns

• Returns a FileHound instance

.isEmpty() -> FileHound

Parameters - None

Returns

• Returns a FileHound instance

.addFilter(fn) -> FileHound

Parameters

• fn(file) - accepts a custom file matching predicate

Returns

• Returns a FileHound instance

.ignoreHiddenFiles() -> FileHound

Parameters - none

Returns

• Returns a FileHound instance

.ignoreHiddenDirectory() -> FileHound

Parameters - none

Returns

• Returns a FileHound instance

.discard(regularExpression) -> FileHound

Parameters

• RegularExpression - accepts a regular expression (as string) matching sub-directories or files to ignore

Returns

• Returns a FileHound instance

.find() -> Promise

Parameters - None

Returns

• Returns a Promise of all matches. If the Promise fulfills, the fulfillment value is an array of all matching files.

Test

npm test

To generate a test coverage report:

npm run coverage

Contributing

• If you're unsure if a feature would make a good addition, you can always create an issue first.
• We aim for 100% test coverage. Please write tests for any new functionality or changes.
• Make sure your code meets our linting standards. Run npm run lint to check your code.
• Maintain the existing coding style. There are some settings in .jsbeautifyrc to help.
• Be mindful of others when making suggestions and/or code reviewing.