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:
-
Should the file appear in the sequence? If yes, return
true
forinclude
. -
Should the search descend into this directory? If no, return
true
forascend
. This value has no effect or meaning for paths that are not directories.
-
Should the file appear in the sequence? If yes, return
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.