# filespy

> Spy on files

Latest version **1.2.4** (published 2021-03-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install filespy
pnpm add filespy
yarn add filespy
bun add filespy
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.4 |
| Published | 2021-03-21 |
| First published | 2021-03-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 72.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 36 |
| Author | Alec Larson |
| Maintainers | aleclarson |
| Keywords | fs, watch, watcher, watchman, watchFile, file, watching, fsevents, inotify, crawl, chokidar |

## Links

- npm: https://www.npmjs.com/package/filespy
- Repository: https://github.com/alloc/filespy
- Homepage: https://github.com/alloc/filespy#readme
- Issues: https://github.com/alloc/filespy/issues
- npm.io page: https://npm.io/package/filespy

## Dependencies (4)

- [slash](https://npm.io/package/slash.md) ^3.0.0
- [glob-regex](https://npm.io/package/glob-regex.md) ^0.3.2
- [binary-insert](https://npm.io/package/binary-insert.md) ^1.2.1
- [@parcel/watcher](https://npm.io/package/@parcel/watcher.md) ^2.0.0-alpha.10

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 1.2.4 (latest) — 2021-03-21
- 1.2.3 — 2021-03-21
- 1.2.2 — 2021-03-21
- 1.2.1 — 2021-03-19
- 1.2.0 — 2021-03-19
- 1.1.2 — 2021-03-16
- 1.1.1 — 2021-03-16
- 1.0.3 — 2021-03-16
- 1.0.2 — 2021-03-16
- 1.0.1 — 2021-03-16
- 1.0.0 — 2021-03-16

## README

# filespy

[![npm](https://img.shields.io/npm/v/filespy.svg)](https://www.npmjs.com/package/filespy)
[![ci](https://github.com/alloc/filespy/actions/workflows/release.yml/badge.svg)](https://github.com/alloc/filespy/actions/workflows/release.yml)
[![codecov](https://codecov.io/gh/alloc/filespy/branch/master/graph/badge.svg)](https://codecov.io/gh/alloc/filespy)
[![Bundle size](https://badgen.net/bundlephobia/min/filespy)](https://bundlephobia.com/result?p=filespy)
[![Code style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](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
```

---
_Source: https://npm.io/package/filespy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._