https://github.com/alloc/filespy
Spy on files 🔍
https://github.com/alloc/filespy
Last synced: 9 months ago
JSON representation
Spy on files 🔍
- Host: GitHub
- URL: https://github.com/alloc/filespy
- Owner: alloc
- License: mit
- Archived: true
- Created: 2021-03-15T21:20:25.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-03-22T16:25:25.000Z (almost 5 years ago)
- Last Synced: 2025-03-24T21:02:30.255Z (11 months ago)
- Language: TypeScript
- Homepage:
- Size: 314 KB
- Stars: 38
- Watchers: 2
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# filespy
[](https://www.npmjs.com/package/filespy)
[](https://github.com/alloc/filespy/actions/workflows/release.yml)
[](https://codecov.io/gh/alloc/filespy)
[](https://bundlephobia.com/result?p=filespy)
[](https://github.com/prettier/prettier)
[](https://paypal.me/alecdotbiz)
> Spy on files
### Features
- Emits files only
- Crawls **asynchronously** before watching
- Powered by `@parcel/watcher` for native performance, event throttling, and [Watchman](https://facebook.github.io/watchman/) support
- Tolerates permission errors
- Has powerful [pattern syntax](#pattern-syntax)
- Handles renamed directories properly
- Exposes the paths being watched
- Exposes the paths that were skipped
- Ensures file paths use forward slashes
- Protects against reentrancy by using `setImmediate` before emitting
- Splits up long-running listeners with `setImmediate`
- Crashes if you don't handle `error` events
- Waits for root directory to exist
## Usage
```ts
import filespy from 'filespy'
const spy = filespy(process.cwd(), {
only: ['*.[jt]sx?'],
skip: ['node_modules'],
}).on('all', (event, file, stats, cwd) => {
// "file" argument is relative to "cwd"
// "stats" is from lstat call
if (event == 'create') {
// File created.
} else if (event == 'update') {
// File changed.
} else {
// File deleted.
}
}).on('error', error => {
// Permission error or watcher failed.
}).on('ready', () => {
// Initial crawl completed. Watcher initialized.
})
spy.dirs // Set of watched directories.
spy.files // Sorted list of watched paths (even directories).
spy.skipped // Sorted list of existing paths that were skipped.
// List all watched paths within a watched directory.
// Returned paths are relative to cwd.
spy.list('foo/bar')
// Stop watching.
spy.close()
```
## Events
```ts
interface {
all(
event: 'create' | 'update' | 'delete',
/** Path relative to cwd */
file: string,
/** Equals null for "delete" events */
stats: fs.Stats | null, // https://nodejs.org/api/fs.html#fs_class_fs_stats
/** The root directory */
cwd: string
): void
/** Permission error or watcher failure */
error(error: Error): void
/** Directory was crawled */
crawl(dir: string, cwd: string): void
/** Watcher is ready */
ready(): void
/** File created */
create(file: string, stats: fs.Stats, cwd: string): void
/** File changed */
update(file: string, stats: fs.Stats, cwd: string): void
/** File deleted */
delete(file: string, cwd: string): void
}
```
## Pattern syntax
Filespy mixes globbing with regular expressions, a concept borrowed from [Recrawl](https://github.com/aleclarson/recrawl).
1. When a path has no separators (`/`), only the basename is matched.
```js
'*.js' // matches 'a.js' and 'a/b.js'
```
2. Recursivity is implicit.
```js
'a/b' // identical to '**/a/b'
```
3. Use a leading separator to match against the root.
```js
'/*.js' // matches 'a.js' not 'a/b.js'
```
4. Use a trailing separator to match all descendants.
```js
'foo/' // matches 'foo/bar' and 'foo/bar/baz' etc
```
5. Regular expression syntax is supported. (except dot-all)
```js
'*.jsx?' // matches 'a.js' and 'b.jsx'
'*.(js|ts)' // matches 'a.js' and 'b.ts'
```
6. Recursive globbing is supported.
```js
'foo/**/bar' // matches 'foo/bar' and 'foo/a/b/c/bar' etc
```