filespy
TypeScript icon, indicating that this package has built-in type declarations

1.2.4 • Public • Published

filespy

npm ci codecov Bundle size Code style: Prettier Donate

Spy on files

 

Features

  • Emits files only
  • Crawls asynchronously before watching
  • Powered by @parcel/watcher for native performance, event throttling, and Watchman support
  • Tolerates permission errors
  • Has powerful 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

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

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.

  1. When a path has no separators (/), only the basename is matched.
'*.js' // matches 'a.js' and 'a/b.js'
  1. Recursivity is implicit.
'a/b' // identical to '**/a/b'
  1. Use a leading separator to match against the root.
'/*.js' // matches 'a.js' not 'a/b.js'
  1. Use a trailing separator to match all descendants.
'foo/' // matches 'foo/bar' and 'foo/bar/baz' etc
  1. Regular expression syntax is supported. (except dot-all)
'*.jsx?' // matches 'a.js' and 'b.jsx'
'*.(js|ts)' // matches 'a.js' and 'b.ts'
  1. Recursive globbing is supported.
'foo/**/bar' // matches 'foo/bar' and 'foo/a/b/c/bar' etc

Dependencies (4)

Dev Dependencies (20)

Package Sidebar

Install

npm i filespy

Weekly Downloads

3

Version

1.2.4

License

MIT

Unpacked Size

74.5 kB

Total Files

16

Last publish

Collaborators

  • aleclarson