uci-utils-watcher/readme.md

A File System Watcher Class

a uCOMmandIt Utility Package

Descripton

An extended emitter class that includes a fileystem watcher (choikar).

Use

import and call the create function with your options or import the Watcher class extend if desired and instantiate with your options

call the async start method and you are up and running

options

opts = {
    source:'./example/repo/**', // what to watch - required!, can be string or array of strings
    ignored:['**/dontwatch.js'], // individual globs
    ignoreList:['./example/repo/.gitignore'], // files containing newline lists of globs
    excludeFrom: ['./example/repo/.gitignore'],  // optional alternative ignore list property compatible with rsync
    debounce: 0,  // default is no debounce
    readyTimeout:10000, // default is 10 seconds to index the files to be watched,
    delDir: false, // default: ignore directory deletion events 
    addDir: false, // default: ignore directory addition events
    unlinkDir:true //  make chokidar emit on deleted directory as well.
}

plus any options supported by chokidar chokidar options

API

methods

registerHandler (func,opts)  // can be called at any time but unexpected problems may arise if called when watcher is already async start(opts)  // starts the watcher which will initializes the files indexing and set the handler function 
stop()  // stops 
remove() completly removes the current watcher.
async restart(opts,force) // first stops the watcher then calls start, if force is true it will reintialize the watcher as well
getWatcher  // returns handle to choikar watcher for choikar methods access

getters

watching ready

events

changed: filepath, type // when a watched file has a change (type will be added,removed,or modified) error: message,error watching: state,options // listening for changes ready: state, options // done indexing files to be watched

handler

default

the built in default handler is probably sufficient for most use cases. It emits a 'changed' event with the file or directory name changed and with a type, that being modified, deleted, added. The default handler also emits a 'install' event if the file is package.json in the root of the source is modified (used for restarting), or a warning if it is deleted or added

function _handler (type, f) {
  log.debug(`file ${f} was ${type}`)
  const fname = path.basename(f)
  if ( fname.toLowerCase() === 'package.json' && path.dirname(f)=== this.opts.source.replace(/\/$/, ''))
    if (type !=='modified') {
      const msg = `a package.json in root of ${this.opts.source} was added or removed`
      log.warning(msg)
      this.emit('warning',f,msg)
      return
    } else{
      this.emit('install', f)
    }
  // user might want to run debounce on the listener for this event
  log.debug({file:f, type:type, msg:'file system changed, emitting'})
  this.emit('changed', f,type)
} // end handler

custom

one can use a custom handler by passing such a function in options or using registerHandler. The handler is passed two arguments the type of the change and the file changed.

atomic issues

Several type of editors write atomically. They typically write a .gpoutputstream file temporily that "trick" choikdar. So by default this watcher ignores these files. Can you included them by passing false for ignore_gpoutputstream. If you still don't get a modified event using these apps (e.g. gedit) you might look at the atomic option and if all else fails usePolling

Chokidar Options

chokidar.watch('file', { persistent: true, ignored: '*.txt', ignoreInitial: false, followSymlinks: true, cwd: '.', disableGlobbing: false, usePolling: false, interval: 100, binaryInterval: 300, alwaysStat: false, depth: 99, awaitWriteFinish: { stabilityThreshold: 2000, pollInterval: 100 }, ignorePermissionErrors: false, atomic: true // or a custom 'atomicity delay', in milliseconds (default 100) });

details here https://github.com/paulmillr/chokidar#api