110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
# 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 |