FileHound
    Preparing search index...

    Class FileHound<T>

    A fluent query for searching the file system.

    Configure a query by chaining methods, then run it with FileHound.find or FileHound.findSync. Once a search has started the query is locked and can no longer be modified.

    import { FileHound, ext } from 'filehound';

    const files = await FileHound.create()
      .paths('/tmp')
      .match(ext('json'))
      .depth(1)
      .find();

    Type Parameters

    Hierarchy

    • EventEmitter
      • FileHound
    Index
    constructor
    depth find findSync getPaths ignoreHiddenDirectories ignoreHiddenFiles ignoreSymlinks includeFileStats iterate match paths skipDirectories type any create

    • Specify the directory search depth. If set to zero, recursive searching will be disabled. Directories at the limit are not searched, but are still returned when FileHound.type includes directories.

      Parameters

      • depth: number

        the maximum search depth (a non-negative integer)

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started.

      RangeError Thrown if depth is negative or not an integer.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .depth(0)
        .find(); // array of file names only in the current directory

    • Asynchronously executes a file search. Once called, the query is locked and can no longer be modified.

      Parameters

      Returns Promise<T[]>

      a Promise of all matches. If the Promise fulfils, the fulfilment value is an array of all matching files

      Emits a match event for each matching file, an error event if the search fails or is aborted and an end event when the search completes.

      import { FileHound } from 'filehound';

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

      console.log(files);

      Giving up on a search after five seconds:

      const files = await FileHound.create()
        .paths('/')
        .find({ signal: AbortSignal.timeout(5000) });

    • Synchronously executes a file search. Once called, the query is locked and can no longer be modified. No events are emitted.

      Returns T[]

      an array of all matching files

      import { FileHound } from 'filehound';

      const filehound = FileHound.create();
      const files = filehound.findSync();
      console.log(files);

    • Returns the paths that will be searched. When no depth is set, any path that is a subdirectory of another search path is removed, as it would otherwise be searched twice.

      Returns string[]

      a copy of the search paths

    • Excludes hidden directories (names beginning with a dot), and their contents, from the search

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .ignoreHiddenDirectories()
        .find();

    • Excludes hidden files (names beginning with a dot) from the results

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .ignoreHiddenFiles()
        .find();

    • Excludes symbolic links from the search. Linked files are not matched and linked directories are not searched.

      Returns this

      the FileHound instance

      By default, symbolic links are followed: a linked file is matched as its target and a linked directory is searched. Broken links, and links back to a directory already being searched, are always skipped.

      Error Thrown if the query is locked because a search has started.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .ignoreSymlinks()
        .find();

    • Returns each match with its stats, as { path, stats }, in place of its path. Stats already fetched by a predicate are reused.

      Returns FileHound<FileWithStats>

      the FileHound instance, typed to return FileWithStats matches

      Error Thrown if the query is locked because a search has started.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .includeFileStats()
        .find();

      files.forEach(({ path, stats }) => console.log(path, stats.size));

    • Asynchronously executes a file search, returning matches one at a time as they are found, in the same order as FileHound.find. Once called, the query is locked and can no longer be modified.

      Parameters

      Returns AsyncGenerator<T>

      an async iterator of matches

      The search runs ahead of the loop by a bounded amount, so a large search can be read without holding every match in memory. Breaking out of the loop stops the search.

      Emits a match event as each match is returned, an error event if the search fails or is aborted and an end event when the search finishes: when every match has been returned, the search fails or is aborted, or the loop is left early.

      import { FileHound, ext } from 'filehound';

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

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

    • Specifies the criteria that files must satisfy to be included in the results. Defaults to matching all files.

      Parameters

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started.

      TypeError Thrown if the query is not a valid matcher.

      import { FileHound, ext } from 'filehound';

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

    • Defines the search paths: the directories to search. Duplicate paths are removed and each path is normalised. Defaults to the current working directory.

      Parameters

      • ...paths: string[]

        one or more directory paths

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started. A path that doesn't exist, or isn't a directory, is rejected when the search runs.

      import { FileHound } from 'filehound';

      const files = await FileHound.create()
        .paths('/tmp', '/etc') // or ['/tmp', '/etc']
        .find();

    • Defines the search paths from an array.

      Parameters

      • paths: string[]

        an array of paths

      Returns this

      the FileHound instance

    • Skips directories by name: a directory whose name matches any of the given names is neither searched nor returned. Use it to keep the search out of directories such as node_modules, which a FileHound.match predicate can only exclude from the results after searching them. Calling it again replaces the names.

      Parameters

      • ...names: string[]

        one or more directory names or globs

      Returns this

      the FileHound instance

      Each name is matched against a directory's name only, not its path, following Node's path.matchesGlob. A plain name, such as 'node_modules', matches exactly, and a glob, such as 'build-*', matches any name it describes. Every directory below the search paths is tested, including linked directories, but not the search paths themselves.

      Error Thrown if the query is locked because a search has started.

      RangeError Thrown if no names are given.

      TypeError Thrown if a name is not a non-empty string, or contains a path separator.

      import { FileHound, ext } from 'filehound';

      const files = await FileHound.create()
        .skipDirectories('node_modules', '.git', 'build-*')
        .match(ext('js'))
        .find();

    • Specifies the types of file system entry to return. Defaults to regular files only.

      Parameters

      • ...types: FileType[]

        one or more file types

      Returns this

      the FileHound instance

      Error Thrown if the query is locked because a search has started.

      RangeError Thrown if no file types are given.

      TypeError Thrown if an invalid file type is given.

      import { FileHound, FileType } from 'filehound';

      const directories = await FileHound.create()
        .type(FileType.DIRECTORY)
        .find();

    • Executes one or more FileHound queries and combines their results

      Type Parameters

      • T

      Parameters

      • ...args: FileHound<T>[]

        the FileHound instances to execute

      Returns Promise<T[]>

      a Promise of all matches. If the Promise fulfils, the fulfilment value is an array of all files matched by any of the queries

      import { FileHound } from 'filehound';

      const files = await FileHound.any(fh1, fh2);

    • Static factory method to create an instance of FileHound

      Returns FileHound

      a new FileHound instance

      import { FileHound } from 'filehound';

      const filehound = FileHound.create();

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods