# 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

```javascript
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](https://github.com/paulmillr/chokidar)

## 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

```javascript
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