node-find

An approximation of GNU find as an asynchronous iterator.

Usage

find(filter, [options])

Return an asynchronous iterator of the files under a starting path, according to search parameters.

Options

• start :: string

  The root of traversal. Default is ['.'].

• maxDepth :: number

  Limit for depth of recursion. The starting path is at level 0. Default is no limit.

• filter :: async (Path) => {include: boolean, ascend: boolean}

  Given a path to a file, asynchronously answer two questions:

  1. Should the file appear in the sequence? If yes, return true for include.
  2. Should the search descend into this directory? If no, return true for ascend. This value has no effect or meaning for paths that are not directories.

Check the tests for examples.

Filters

Shell patterns

Only GNU find shell patterns are supported: * for any sequence of characters, ? for a single character, and [, ] surrounding a character class. These special characters may be matched explicitly by escaping them with a backslash (\).

To get the "globstar" (**) matching popular in node-glob, use a path filter with a simple shell pattern.

Matchers

• name(string)

  Includes a path if the last component of the pathname matches the given shell pattern.

• path(string)

  Includes a path if the full pathname matches the given shell pattern. Path component separators (e.g. / on Linux) are treated as normal characters and do not have to be matched explicitly.

• regex(string | RegExp)

  Includes a path if the full pathname matches the given regular expression.

• never

  Includes no paths.

• always

  Includes every path.

• type(string)

  Includes a path if it has the specified type. The type symbols are taken from GNU find.

  • 'b' block device
  • 'c' character device
  • 'd' directory
  • 'f' regular file
  • 'l' symbolic link
  • 'p' FIFO
  • 's' socket

Operators

• prune(filter)

  Prevent descent into directories that match the given filter, but still include them in the sequence!

• and(...filters)

  The logical AND operator. Includes a path if all subfilters include the path. Ascends if any subfilter that includes the path chose to ascend. Stops evaluating filters after the first exclusion.

• or(...filters)

  The logical OR operator. Includes a path if any subfilter includes the path. Stops evaluating filters after the first inclusion. Ascends if that subfilter chose to ascend.

• not(filter)

  The unary NOT operator. Includes a path if the subfilter excludes it. Passes through the subfilter's descision on ascent.

License

MIT