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
• Supports events for efficient file processing

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);

Defining multiple search locations

Find all JSON files in '/some/dir1' and '/some/dir2'

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

const myPaths = ['/some/dir1', '/some/dir2'];
const jsonFiles = FileHound.create()
  .paths(myPaths)
  .ext('json')
  .find();

Using callbacks

Find all empty text files in /tmp:

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

Binding to match and end events

Bind to a 'match' event to process each file on match:

const filehound = FileHound.create();
  filehound.find();

  filehound.on('match', (file) => {
    console(`process ${file}`);
  });

  filehound.on('end', (file) => {
    console(`search complete`);
  });

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.

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.

Parameters

• path - one or more directories (as variable arguments) or a reference to an array of directories

Returns

• Returns a FileHound instance

.path(path) -> FileHound

Directory to search.

Parameters

• path

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

.modified(dateExpression) -> FileHound

Parameters

• dateExpression - accepts a time unit. Time units are:

  • minutes, specified using minutes, m, mins, min.
  • hours, specified using hours, h, hour.
  • days, specified using days, d, day.

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

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

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

If no comparison operator is specified, equality is used by default.

Examples:

• equal to 10 days: 10
• equal to 10 minutes: == minutes
• less than 10 hours: < 10 hours
• greater than 50 minutes: >50minutes
• less than 50 minutes: <50m

Returns

• Returns a FileHound instance

.accessed(dateExpression) -> FileHound

Parameters

• dateExpression (see .modified)

Returns

• Returns a FileHound instance

.changed(dateExpression) -> FileHound

Parameters

• dateExpression (see .modified)

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.
• Any API changes should be fully documented.
• 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.