Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thejohnfreeman/node-find
Approximation of GNU find as a vinyl file stream.
https://github.com/thejohnfreeman/node-find
Last synced: 2 months ago
JSON representation
Approximation of GNU find as a vinyl file stream.
- Host: GitHub
- URL: https://github.com/thejohnfreeman/node-find
- Owner: thejohnfreeman
- License: mit
- Created: 2014-08-10T21:56:41.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2021-03-30T13:42:33.000Z (almost 4 years ago)
- Last Synced: 2024-10-17T06:47:19.264Z (3 months ago)
- Language: TypeScript
- Size: 51.8 KB
- Stars: 6
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# node-find
An approximation of GNU find as an asynchronous iterator.
[](https://www.npmjs.com/package/node-find)
[](https://github.com/prettier/prettier)
[](https://github.com/thejohnfreeman/node-find/actions/workflows/test.yml?query=branch%3Amaster)
[](https://coveralls.io/github/thejohnfreeman/node-find?branch=master)
[](https://codeclimate.com/github/thejohnfreeman/node-find)
## 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`.
1. **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.
[tests]: https://github.com/thejohnfreeman/node-find/blob/master/test/tests.js
### 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.
[node-glob]: https://github.com/isaacs/node-glob
##### 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](http://opensource.org/licenses/MIT)